ANNE v2.2.4 John Elliott Abstract ANNE is an Amstrad PcW16 emulator for UNIX and Windows. It only emulates the PcW16; use JOYCE for other PCW / PcW models. Table of Contents Introduction Copyright Copyright 1997,2001-7,2010 John Elliott. Parts copyright 1994, 1995 Ian Collier; other parts copyright 1987, 1999 Caldera[footnote: The copyright message in the source files names Caldera. Actual ownership of the copyrights has probably since passed to DRDOS Inc. ]. ANNE can be distributed freely under the conditions of the GNU General Public License (sic) - see the file COPYING. What ANNE does ANNE emulates a PcW16 computer - an 8-bit computer intended by Amstrad as a word processor, and manufactured around 1996. What's new? Since v2.2.0: The Windows version is distributed with the latest SDL.DLL. Various compilation fixes on Unix platforms. Since v2.1.0: A crash that occurs when trying to load the rescue disc has been corrected. Initial support for compiling under Mac OS X has been added. It is now possible to use a folder on the host computer as a CP/M disc. Native GSX support is now present. Can now boot CP/M. Successfully detects when a disc image has been changed. Does not let the mouse pointer go off the bottom of the PcW16 screen. Installation from a .CFI file (rather than a physical PcW16 rescue disc) now works correctly. With graphics acceleration turned on, the word processor display is not corrupted by scrolling. Floppy acceleration is a whole lot better than it was before. When you create a new disc image file, you will be asked whether it should be 720k or 1.4Mb. It will then be formatted, so you don't have to use the PcW16 file manager to format new discs. Instead, answer yes when it asks you if you want to create PcW16 folders on the disc. Concepts When moving from a PcW to an emulator, the biggest change you have to accustom yourself to is the way that ANNE handles discs. Real PcW16s use real floppy discs[footnote: The PCW16 design allowed a hard drive interface to be added. ANNE does not emulate this. ]; you use the recovery disc to reload the system after a crash, a data disc to save your work on, and so on. It is possible for ANNE to use real disc drives in the same way that a PcW does. However this is pretty slow and awkward; since the PC's got a hard drive, you might as well use it. Disc image files Each floppy disc is read into the PC's hard drive and stored as a “disc image file”. This is a one-time process; once the disc image files are created, the discs themselves are no longer needed. Disc image files have a number of advantages: They are much faster than real floppy discs. You don't have to be shuffling a stack of floppies every time you want to use ANNE. If you want more discs, you don't have to go to the shop to buy them. You just create more disc image files. By convention, these have names ending in “.dsk”. So instead of having a “manuscripts” disc, you would have a disc image file called “manuscripts.dsk”. To normal Unix or Windows software, “ manuscripts.dsk” is just one file, but PcW programs see it as a disc with any number of PcW files on it. One consequence of this is that the PcW16's floppy drive has nothing to do with your PC's real floppy drives. You can be working with a “disc” in the PcW's drive even when there's nothing in your real floppy drive(s). Converting your PcW discs to disc image files is covered in section [sec: setup]. Disc image folders ANNE 2.1.8 and later can use folders instead of CP/M disc image files. In this system, one PcW disc corresponds to one PC folder. This has the advantage that each PcW file corresponds exactly to one PC file. For example, you could put text files in that folder, and then use the PcW's “Import” facility to import files from them. Floppy Acceleration When you have floppy acceleration turned on, ANNE doesn't use disc images any more. When programs refer to the 'disc drive', they are actually looking at a directory called PcW16FS on your hard drive. This is more convenient if you want to share files between the PcW16 environment and the rest of the world, and you don't have to worry about disc images only holding 1.4Mb. ROMs A real PcW16 has 1 megabyte of flash ROM, which holds the contents of the Cabinet, the built-in software, and the user settings. In the case of a program crash, the contents of the flash ROM could be lost, forcing a time-consuming reload from the recovery disc and data backups. ANNE doesn't just use one flash ROM - it allows you to choose from several. One (called “Previous session”) is automatically saved when you leave ANNE; another (“Empty system”) is created when the recovery disc is first read in. It is possible to save others at any time; for example, if you have a Cabinet full of documents, you can save a copy of the ROM, and revert to that later if something goes wrong. The MENU key ANNE requires a Windows-style keyboard with a Menu key. On most keyboards, Menu is between AltGr and Ctrl, to the right of the space bar. Under Mac OS X, there is no Menu key (even if you've plugged in a PC keyboard, SDL doesn't recognise the key) and you should use Command-F9 (Windows+F9 on a PC keyboard) instead. Compiling ANNE If you have downloaded ANNE as a binary for your platform (eg: the full Windows install, or an RPM), you can skip this section. To compile ANNE, you will need: SDL, the Simple DirectMedia Layer: . You need version 1.0.8 or later. libxml, the xml parser used by GNOME . ANNE was tested with version 2.2.6. libpng, the image library. . You need version 1.0.6 or later. You should be able to compile with the commands: ./configure make sudo make install On systems with a GCC version earlier than 3.0, the first line should be “./configure --with-ministl”. To cross-compile ANNE for Windows, you need the XMINGW32 cross-compiler pack from , and MINGW32 versions of the above libraries. ANNE on Mac OS X I have successfully compiled ANNE on a Mac OS X (10.4.2) system. The process (and indeed MacOS X support in general) is pretty new and unpolished. Firstly, the three libraries mentioned above (SDL, libxml and libpng) had to be compiled from source and installed using their “ make install” commands; pre-packaged OS X versions didn't seem to be suitable. Secondly, the configure script needed to be told what the host system was: ./configure --host=powerpc-darwin-apple8.2.2 make sudo make install Thirdly, this builds an ANNE that is still very much a UNIX application; there's no application icon, no native OS X menu, and so on. Known bugs This version of ANNE contains, or is thought to contain, the following bugs: Under MacOS X in full-screen mode, the mouse pointer can leave stray pixels where it has been. The serial port support is untested. It is possible to use QTERM under CP/M, but the SIO device driver (SIO.FID) has not been tested. The emulated PcW hangs if, from the front screen, you click 'Help' then 'Index'. Internet resources The latest versions of ANNE- and any future updates - will be downloadable as part of the JOYCE suite, from . Announcements of new ANNE releases, if any, will be made to the newsgroup . It is also on-topic to discuss ANNE in this newsgroup. Setting Up Directory organisation Under Windows ANNE uses the same directories as its sister emulator JOYCE. These comprise two directories - a “system” directory common to all users (eg, “C:/Program Files/Joyce/lib” and a “user” directory (eg: “C:/My Documents/Joyce”). Each of these directories will have subdirectories called Boot (boot files and boot disc images) and Disks (all other disc images). In the remainder of this document you will see directory names which look like “~/Joyce/Boot”; you should take the “~” to stand for the “My Documents” directory. If you don't want ANNE to put its files in “My Documents”, then you can override it. In ANNE, press [f9] for the menu, [f6] for settings, and select “General”. Then enter the new directory name, and press RETURN. You will need to copy the “Joyce” directory from “My Documents” to the new directory you specified. Under Unix ANNE uses two directories - a “system” directory common to all users (by default, /usr/local/share/Joyce - see Appendix [sec: admins] ) and a “user” directory for each user (by default, ~/Joyce). Each of these directories will have subdirectories called Boot (boot files and boot disc images) and Disks (all other disc images). Running ANNE for the first time You will need: A version of ANNE that installed correctly. A screen capable of 800x600x256 graphics. ANNE may well be faster in 256 colour mode than in (say) 16-bit mode. One of the following: A PcW16 rescue disc; A disc image of the PcW16 rescue disc, that you previously generated; The rescue disc in .CFI format from Cliff Lawson's web page: The ANNE command Under Windows, ANNE should be run from the Start Menu. Under Unix, the command to use is either “xanne” (to run in a window) or “xanne -f” (to run full screen). Other command line options are given in section [sec: cmdline]. Adding boot ROMs The first time ANNE is started, it will detect that no boot ROM is present. You will be asked to provide it with a rescue disc. The next menu that appears asks you for the location of the rescue disc to use. If you are using real floppies, then select the correct drive (A: or B:). If you are using a pre-prepared DSK file, choose the correct file. If you are using a .CFI file, choose the file and then select “ Advanced”. On the menu that appears, select “.CFI - compressed raw”. Next select “Continue”. If all goes well, the boot ROM will now be created and the boot menu will appear. The only usable option will be “Empty system (Boot ROM only”) so select that. You should then see the PcW16 memory test, followed by the “Fatal OS checksum error” message. Use the ANNE menu (see below) to insert the rescue disc again, and click the “power switch” icon. If you get a “Disk bootstrap error”, click the power switch again. When the OS install is complete and you have entered your user details, use the ANNE menu to save the current system as a boot ROM (f2=Disc; Disc management; Save current ROM as boot ROM). Call it something like “Full system”. Running ANNE for the second and subsequent times When ANNE has been set up, it will display a boot menu when started. The menu will offer the following options: Previous session The ROM saved when you last used ANNE. You would normally choose this option, unless the session has been corrupted by a program crash or you want to load an alternative ROM. n. title ROMs that have been saved at earlier points. There will usually be one called “Empty system”, representing the state of the system just before the recovery disc is loaded. Other... Load a ROM from a disc file. In Use What is emulated The Z80. 2MB of memory and 2MB of Flash ROM. The screen. The keyboard. The real-time clock A Centronics-only printer interface. You can print to a disc file or a UNIX command (eg, “lpr” for direct printer output). The mouse (either attached to a COM port, or directly driven). You will need a three-button mouse for the full effect. The serial ports (emulation of these is rather sketchy) The beeper. The LocoLink interface (over the parallel port). What is not emulated The optional hard drive. How the disc drive is handled The basic concept of disc image files was described in section [sec: concepts] . There are several subtleties to be aware of: Ejecting a disc To eject a disc, press the MENU key (OS X: Command+F9) for the ANNE menu, then [f2] (Disc). If there is a disc in the PCW16's drive, you can eject it by selecting the corresponding “eject” option. Remember that ejecting discs from ANNE's emulated drive doesn't have anything to do with whatever floppy drives are actually fitted to the PC. Command-line options If you want ANNE to start with a disc in its emulated drive, then use -A with a filename: xanne -A documents.dsk will start up with "documents.dsk”. in the drive. To start up without asking which boot ROM to use, use the -E option with a filename: xanne -E bootfile.rom Non-floppy discs The following JOYCE utilities have not been tested on ANNE. Some may work. ANNEDRV.FID gives the emulated PcW16 a hard drive (available only under CP/M). It uses a similar "disc image file" system to the floppy drives, but the image files can be up to 8Mb in size. REDIR.COM allows you to use one or more Unix directories as CP/M drives. It requires CP/M. This avoids the problem that the host PC can't see "inside" image files without extra software. IMPORT.COM and EXPORT.COM will copy single files into or out of the ANNE environment. They require CP/M. All these utilities are on the file ANNEUTIL.DSK. You can get at them with a command something like: xanne -A=/usr/local/lib/Joyce/Disks/anneutil.dsk and then start CP/M using “Run external program”. REDIR.COM and its companion programs are in Group 1; the others are in Group 0. Floppy Disc Acceleration As mentioned in section [sec: concepts], floppy disc acceleration makes a directory on your hard drive appear to be the PcW16 floppy drive. This does not work with CP/M; for CP/M discs, use the “Folder” option in the “Enter filename for disc image” menu. What if the speed is wrong? If ANNE is too slow One solution is to increase the CPU speed. Press [MENU], then [f6] and select 'General'. Then enter the new speed. It may also be possible to improve the performance of ANNE by changing the video refresh frequency. This is normally 12, but it can be reduced to improve performance. If it is reduced to 3.75, for example, then programs may appear a little jerky, but ANNE should run at its full speed. To change the video refresh frequency, start ANNE. At the opening screen, press [MENU], then [f6] and select 'Video'. Then enter the new frequency and press RETURN. If ANNE is too fast The built-in speed regulation in ANNE should stop it running too fast. Possibly you could reduce the overall speed: press [MENU], then [f6] and select 'General'. Then enter a new speed. Peripherals in ANNE The keyboard The keyboard is laid out to match the PcW16's own keyboard - a UK-layout 102-key arrangement. The following keys have different captions on the PcW16: [This is for a UK keyboard with XFree86. Other X servers may behave differently]. +--------------+----------+--------------------------------+ | PC key | PCW key | Notes | +--------------+----------+--------------------------------+ +--------------+----------+--------------------------------+ | ESC | STOP | ^C under CP/M | +--------------+----------+--------------------------------+ | F9 | Blue | Under Mac OS X, F9-F12 trigger | +--------------+----------+--------------------------------+ | F10 | Yellow | Exposé, so you may have to use | +--------------+----------+--------------------------------+ | F11 | Green | (eg) CTRL+F9 instead. | +--------------+----------+--------------------------------+ | F12 | Red | | +--------------+----------+--------------------------------+ | Scroll Lock | UNDO | ESC under CP/M | +--------------+----------+--------------------------------+ | Pause | Help | | +--------------+----------+--------------------------------+ | Alt | Task | | +--------------+----------+--------------------------------+ The Mouse The PcW16 uses a Mouse Systems type mouse, connected to its second serial port (referred to by ANNE as COM3:). ANNE can emulate the mouse as either: No emulated mouse. Serial mouse on COM1 (the mouse is in the wrong socket) Serial mouse on COM3 (the mouse is in the right socket) Update ROSANNE directly (the ROSANNE mouse coordinates are updated directly, which produces much better results than the emulated serial mouse options) To choose which emulation is selected, press [MENU] in ANNE; then [f6] for Settings, and choose Mouse. It is possible to use ANNE with a real PcW16 (or compatible) mouse - any serial mouse that uses the MouseSystems protocol should be suitable. To do this, choose 'No emulated mouse', plug the mouse into a serial port, and set the PcW16's COM3 to use that port. The disc drive Instead of a real disc drive, ANNE works with “disc image files” on the computer's hard drive. These are fully described in sections [sec: concepts] and [sec: morediscs]. If Rosanne acceleration is turned on (section [sec: accel]), then instead of disc image files, ANNE will use a directory on your hard drive. The LocoLink interface ANNE allows two forms of LocoLink communication (only one under Windows, though). In each case, you must have suitable software (LocoLink or PcWLink). LocoLink to a real computer (requires Linux) ANNE will act as the master. Connect the parallel port of your Linux box to the other computer (if it's another PC, use a LapLink cable; if it's a PcW, use the original LocoLink cable). Go into the settings for the printer port, and set it to “ Output to parallel port”. Then select the appropriate parallel port (normally /dev/parport0 or /dev/parport1). LocoLink to another emulator Go into the settings for the printer port and set it to “output to Socket”. On the screen that appears, select the correct socket type and name (see below) and ensure the “Client (Normal)” option is ticked. Socket types and names UNIX domain sockets (not supported on Windows) can be used to communicate with other emulators on the same computer. They work pretty much like normal files, and their names are normal filenames; so, for example, one might be called “ /tmp/locolink.socket”. When you are establishing a link, it is important that both ends are using the same socket name. TCP/IP sockets can be used to communicate with other emulators not only on the same computer, but across a network or the Internet. However, ANNE does not perform any security checks on socket connections, so I strongly recommend that you do not use TCP/IP sockets while connected to the Internet. For a LocoLink master, the name of a TCP/IP socket is formed “ host:port” - for example, “localhost:8256”, “127.0.0.1:8512” or even “www.somewhere.com.invalid:8080”. The ANNE Menu If you press the Menu key (OS X: Command+F9), a menu will appear at the top of the screen. It offers the following options: ESC=return to ANNE Leaves the menu system. f1 = Help Display the keyboard layout onscreen. f2 = Discs Options for the floppy drive. Use this to "insert" and "eject" discs, to read floppy discs into the ANNE environment, and to modify boot ROM settings. It brings up the Discs menu below. f5 = Reboot Simulates turning the PcW off and then on again. f6 = Settings Settings for all aspects of the emulator. The Settings menu will appear. f7 = Debug Display the Debug menu ([sec: dbgmenu]). f8 = Action Display the Action menu ([sub:The-Action-Menu]). f10 = Quit Leave ANNE. You will be asked for confirmation. Under OS X, use Command+F10, because F10 by itself triggers Exposé. The Action Menu This menu has only one option: “Select PCW screen.” This is intended for use with GSX programs (such as DR Graph) which exit without shutting GSX down properly. In such cases, the program will appear to hang, but selecting the PCW screen will display the A> prompt. The Debug Menu There are four options here, intended mainly for advanced users or ANNE developers. “Debug mode” puts the system in debug mode. This has no effect in the current release. “CPU state” displays the values of the Z80 registers. “RAM dump” writes out the contents of RAM to a file in the current directory called “anne.ram”. This is not a full snapshot facility; memory dumps can't be reloaded, and they don't contain CPU state. “Power switch” simulates the power switch being pressed or released. The Disks menu The Disks menu displays the status of the floppy drives, and allows you to eject or insert discs. Each drive has three lines in the menu: The first line reads either “Drive A: (Ejected)” or “Drive A: (Filename)”. This shows whether there is a “disc” (.DSK file) in the drive or not. The second line reads either “Eject” or “Insert...” depending whether there's a disc in the drive. “Eject” ejects the current disc (.DSK file); while “Insert...” brings up a window asking for the file to insert. You can also “insert” a real floppy drive; this allows the emulated PcW to access a real drive directly (if slowly). If you change the disc in the real drive, you may need to “eject” and “insert” the real drive, so that the PcW's own software can tell that the disc has changed. If you ask to “insert” a folder, and the folder you select has not previously been used in this way by JOYCE or ANNE, then you will be asked what format the folder should pretend to be in. The bottom line for each drive reads “Read only”. If there is a tick beside it then the write protect holes on the disc have been opened and it cannot be written to. If you select“Disc management...” then a menu appears allowing you to read in extra floppy discs, or convert .DSK files back to real discs. The Disc Management menu There are six options: Add a boot ROM from a file - Reads in a boot ROM and adds it to the opening menu. Save current ROM as boot ROM - Saves the current ROM file and adds it to the opening menu. Rename a boot ROM - Allows you to change the caption associated with a boot ROM. Delete a boot ROM - Removes a boot ROM from the opening menu. Use this option with caution! Convert floppy to ANNE.DSK file - Read in a normal (data) disc, storing the new disc image file in the “user discs” directory. Write .DSK file back out to floppy - Convert a disc image file (either normal or start-of-day) back to a floppy disc. The Settings menu Choose the item of hardware for which you want to make changes. Note that if you make a change such as disconnecting or connecting an interface, the emulated PcW may not pick it up until the next reboot. Disc drives Note: The menus in this section only allows you to create configurations that could exist on a real PcW16. By manually editing ~/Joyce/annehw.xml, you can create “impossible” configurations, such as a system with two floppy drives (CP/M and Rosanne won't detect the second one.) If the configuration is “ impossible”, the menus will look different as they attempt to accommodate the changes. The settings in this menu are: Drive A: settings: This brings up its own menu, allowing you to set what type of disc drive is attached to the PcW. The default type (“720k 3.5”) in fact supports 1440k disc images as well. If you want to emulate 5.25” drives or anything else unusual, select “other” and manually enter the drive type, the number of cylinders[footnote: The drive documentation may call this figure the number of tracks rather than the number of cylinders. Either way, it's usually 40 or 80. ] it can access, and whether it's single or double-sided. Extra drives This menu allows you to set up drives C: - L: and N: - P:. Obviously these drives don't exist on real PcW16s, but they can on an ANNE system, though only under CP/M. You will need to have a copy of ANNEDRV.FID on your start-of-day disc for these drives to become available - see section [sec: joycedrv]. For each drive, you can set it up in three ways: As direct access to the PC's floppy drives. As a floppy drive that accesses a standard disc image file, just like the emulated A: drive. As a hard drive with 8Mb of storage. The hard drive will also be stored on a .DSK file, but this .DSK file will not be usable in emulated floppy drives. To set up a drive, choose it from the list. Then choose or enter the filename and drive type, as listed below: +-----------------------------------------+--------------+---------------+ | Type of drive to use | Choose file | Choose option | +-----------------------------------------+--------------+---------------+ +-----------------------------------------+--------------+---------------+ | Floppy drive A: or B: | A: or B: | floppy drive | +-----------------------------------------+--------------+---------------+ | Floppy drive using standard image file | .DSK file | floppy drive | +-----------------------------------------+--------------+---------------+ | Hard drive using special image file | .DSK file | hard drive | +-----------------------------------------+--------------+---------------+ Memory This allows you to set the memory size of your emulated PcW. If your computer is running very low on memory, the “Current memory size” may be less than requested. By default, ANNE uses maximum values - 2Mb of Flash ROM and 2Mb of RAM. If you want it to behave like a real PcW16, set both of these to 1Mb. General options This screen allows you to choose the speed at which ANNE should run. Mouse The mouse settings available here are: Emulation mode: No mouse, Mouse on COM1:, Mouse on COM3: and Update ROSANNE directly (see section [sec: mousetypes]). Video The Video settings allow you to change: “Video refresh” - the number of times per second that the screen is redrawn. You can go up to 50Hz (ie, the screen is redrawn 50 times a second) or down to 0.01Hz (the screen is drawn once every 10 seconds). The default setting in ANNE is 12Hz, which is fine for nearly all programs. The beeper is usually emulated using the PC's sound card. You can also have it manifest as a red flash of the screen (“Visual Beeper”) or silence (“Disable beeper”). Whether the PcW has a colour monitor (the default), a monochrome white monitor (like the real PcW16) or a monochrome green monitor. Printer The following settings are available for the parallel printer port: Connected/Disconnected: Is the printer connected to the PcW? Output to file: Output goes to a disc file. When you select this option, you are asked for the filename to send the output to. Output to UNIX command: Output goes to a Unix pipeline. You can use this to send output to the Unix printing system (enter “lpr” here, with any appropriate options). Output to parallel port : Output goes to a real live parallel port, with no processing. This can be used to LocoLink to a real PcW. Output to socket: Output is sent to another process, over a socket. This can be used to LocoLink to an emulated PcW (using JOYCE v2.1.0). Under Windows, you also get the option to send data to LPT ports. Save settings If you do not save the settings, they will remain in force only for the duration of your current ANNE session. The settings will be saved to the file Joyce/annehw.xml in your home directory. Rosanne Acceleration Rosanne Acceleration allows certain functions normally performed by the PcW16's Rosanne operating system to be taken over by the emulator. To turn acceleration on, press the Menu key, then [F6] for the Settings menu, and select “Rosanne acceleration”. If there is no tick by 'Enabled', press SPACE. You will then see a list of further options, each of which can be ticked and unticked as required. In general, acceleration replaces parts of Rosanne with calls to special functions in the emulator. This can greatly improve performance, though possibly at the cost of compatibility for some programs. Rosanne acceleration has been tested on Rosanne v1.12; it may or may not work with other versions of Rosanne. Acceleration must be turned off during a reload from the rescue disc. Memory Test Ticking this option will cause the “PLEASE WAIT. CHECKING MEMORY” screen to be skipped. Floppy disc If this option is ticked, then instead of using a disc image file for its floppy drive, ANNE will use a directory on the hard drive ( ~/Joyce/PcW16FS). This has a number of advantages: It's faster. You can get files in and out of the PcW16 environment much more easily. The resulting drive is not limited to 1.4Mb. The directory does not have to exist; to create it, turn on floppy disc acceleration, go into the File Manager, and press Control-L. Note that when floppy disc acceleration is turned on, asking ANNE to insert or remove disc images will have no effect. Graphics If this option is ticked, several low-level graphics operations will be implemented in native code. This considerably improves the speed of drawing of menus, dialogs, and those huge buttons on the front screen. ANNE Utilites The following utility programs are supplied with ANNE. They are designed to access features of the emulator which have no equivalent on a real PcW. You will find them on the disc image “ utils16.dsk”. ANNEDRV ANNEDRV.FID is a file which is used to add one or more extra disc drives to CP/M running within ANNE. The first of these drives will usually be drive C:. Unless the settings are changed (see section [sec: extradrv]) the drives will be set up as 8Mb hard drives, called ~/Joyce/Disks/c.dsk, ~/Joyce/Disks/d.dsk, etc. This can be used to share files between an install of JOYCE and an install of ANNE. The drives cannot be accessed from Rosanne. DDJOYCE.PRL DDJOYCE is new in v2.1.7. It is a GSX driver for the host PC's graphics screen, allowing high-resolution colour graphics to be used from CP/M. To use it, edit your ASSIGN.SYS file. Remove the entry which reads 01 @:DDSCREEN and replace it by 01 @:DDJOYCE DDJOYCE has been tested with the Digital Research programs DR Draw and DR Graph, with the following issues: My copy of DR Graph insists on trying to access drive B: all the time, causing invisible “Please insert the disc for drive B:” messages. The program then appears to hang until you press RETURN to acknowledge the message. When DR Graph shuts down, the screen goes blank. This is because DR Graph does not make a proper 'close workstation' call when it terminates. Use the Action menu to switch back to the PcW16 screen. DR Draw works correctly, though text rendering is rather ugly. DOSDIR DOSDIR displays the contents of a directory in the host filesystem (the name DOSDIR is for compatibility with MYZ80). Syntax is: DOSDIR or DOSDIR {x:/path/}filespec Note that if you include a path you must include a filename. The command DOSDIR C:/IMAGES/ is invalid, but DOSDIR C:/IMAGES/*.* is valid. To get lower-case commands, use: A>DOSDIR \ DOSDIR>/usr/local/bin/* EMULIOS.RSX EMULIOS allows Digital Research Logo to use the 800x600 screen. To set it up, use the following commands (under CP/M): PIP EMULOGO.COM=LOGO.COM GENCOM EMULOGO GENCOM EMULOGO EMULIOS - Then EMULOGO.COM will behave as LOGO.COM, but using the 800x600 screen. The following commands will behave differently: setpc Allows a number from 0 to 255 setbg Allows a number from 0 to 255 savepic The .PIC file saved is in Windows BMP format, and can be exported, renamed to .BMP, and loaded by paint programs. loadpic The .PIC file loaded must be in Windows BMP format and have 256 colours, but its size does not have to be 800x600. EXPORT EXPORT will write CP/M files out as UNIX files. It respects exact file sizes. The syntax is: EXPORT cpmfile { [O] } EXPORT unixfile=du:cpmfile { [O] } The first form of the command produce a UNIX file with the same name as the CP/M file. The second form creates a UNIX file with a name that may be different from the CP/M name. If you're using UNIX rather than Windows, beware: because the CP/M CCP renders all filenames into uppercase, it's very unlikely you'll be able to pass directory names to EXPORT; if you say EXPORT /home/fred/cpmfile EXPORT.COM will see "/HOME/FRED/CPMFILE", which probably won't exist. To get round this, use: A>EXPORT \ EXPORT>/home/fred/cpmfile IMPORT IMPORT will read UNIX files into the CP/M filesystem. It sets exact file sizes. The syntax is: IMPORT {/path/}hostfile { [O] } IMPORT du:=/path/hostfile { [O] } IMPORT du:cpmfile=x:/path/hostfile { [O] } The first form imports the named file (or files) to the current drive and user area. The second form imports the file (or files) to the specified drive and user area, keeping the original name(s). The third form imports the files, changing their name(s) to match the provided CP/M filename(s). If the [O] option is present, existing CP/M files with the same name as an imported file will be overwritten without asking. Otherwise you are asked for confirmation. Both filenames may include wildcards, and the second and third forms can include CP/M driveletters and user numbers: A:IMPORT \ IMPORT>2F:*.ASC=/usr/doc/*.txt will import all the .txt files in /usr/doc to drive F, group 2. Filenames are expanded case-sensitively, so you will normally need to use the backslash, as above, to get lower-case letters into the command line. QUIT Syntax: QUIT { number } { [O] } QUIT will exit ANNE. With no parameters, it will check whether there are files on drive M: which may need saving, and if there are it will ask for confirmation. The number parameter is the error level which ANNE should return. If there is no number parameter, ANNE returns 98. The [O] option disables the M: drive check and quits immediately. REDIR REDIR allows you to use one or more PC directories as drives under CP/M. See the separate file REDIR.DOC for more information. VGA and VGACOM VGA.FID allows CP/M programs to make direct use of the PC screen and keyboard. This gives more text on the screen and faster output. Once VGA.FID has loaded, type VGACOM ON to activate it, and VGACOM OFF to deactivate it. Your PcW screen will now be 100 columns x 36 lines. Nearly all the normal PcW escape codes are supported, which should enable character-based programs to be run. Since screen output is now being done by the host PC's processor, you should notice an improvement in speed. The following escape codes work differently in the 800x600 VGA mode: ESC b / ESC c set colours (so the numbers in the PALETTE command actually have meaning). ESC y sets 32x90 mode. ESC z sets 36x100 mode. ANNE utilities (PC hosted) If you don't want to use ANNE's own methods for converting between disc files and image files, you can also use the dsktrans program, which is installed with ANNE. The command to use is either: dsktrans /dev/fdn dskfile - Floppy disc to image file or dsktrans dskfile /dev/fdn -otype floppy - Image to floppy disc. DSKTRANS isn't as versatile as CPCTRANS (for example, it can only handle discs in recognisable PcW or +3DOS formats) but it doesn't need telling what sort of disc it is using, and it is a native (not DOS-hosted) program. Recent Changes New in v2.2.1: Updated to the latest LibDsk and Lib765, to deal with a crash caused by buffer overflow. New in v2.2.0: Minor code cleanups only. New in v2.1.9: Added Meta+F9 as an alternative for Menu, allowing ANNE to be used in Mac OS X. Other changes to improve performance on OS X. Updated LibDsk to 1.1.9, fixing a bug in rcpmfs for files saved as User 1. New in v2.1.8: Exposed the 'rcpmfs' functionality in LibDsk, allowing folders to be used as disc images. New in v2.1.7: Native GSX driver, using Digital Research GEM code released under the GPL. Added 'Select PCW screen' command. New in v2.1.4: Bug fix in mouse acceleration; the mouse pointer can't go off the bottom of the screen any more. Bug fix: The floppy changeline is emulated correctly. Bug fix: ANNE can tell the difference between 720k and 1440k disc images. This allows CP/M to boot from a 720k disc image. New in v2.1.3: Bug fixes in the graphics and floppy acceleration code. Compatibility with the built-in applications is now much improved. Bug fix: Installing from a .CFI file now works correctly. When browsing for a disc image, does not default to the /dev directory (Unix) or drive A: (Windows). Floppy disc image files are formatted by ANNE when they are created. New in v2.1.2: Added native acceleration options. Compiles without modification under gcc 3.2 (if configured with the --with-stl option). New in v2.1.0: First release. For Unix system administrators First and foremost, don't run ANNE as the root user! ANNE gives the PcW programs within it various methods to access the host filesystem; it is entirely possible that a malicious PcW program running within ANNE could damage important Unix files. It is possible to set up a system-wide installation of ANNE with default settings, boot discs and other discs. To do this, first set up the desired configuration as a normal user. Then copy the following files: From ~user/Joyce to /usr/local/share/Joyce: annehw.xml From ~user/Joyce/Boot to /usr/local/share/Joyce/Boot: anne*.rom and annebt.xml From ~user/Joyce/Disks to /usr/local/share/Joyce/Disks: Any other .dsk files that should be common. This will then become the default configuration on your system. Users will still be able to change settings or add additional discs; these will be saved to their local configuration directories. Keyboard codes Note that many of these keys don't exist in a standard PC keyboard. For example, the PC keyboard has no “$” key (it uses SHIFT + 4 instead) so assigning codes to that key will have no effect. +-------+---------------+ | Code | Key | +-------+---------------+ +-------+---------------+ | 8 | Backspace | +-------+---------------+ | 9 | Tab | +-------+---------------+ | 12 | Clear | +-------+---------------+ | 13 | Return | +-------+---------------+ | 19 | Pause | +-------+---------------+ | 27 | Escape | +-------+---------------+ | 32 | Space | +-------+---------------+ | 33 | ! | +-------+---------------+ | 34 | “ | +-------+---------------+ | 35 | # | +-------+---------------+ | 36 | $ | +-------+---------------+ | 38 | & | +-------+---------------+ | 39 | ' | +-------+---------------+ | 40 | ( | +-------+---------------+ | 41 | ) | +-------+---------------+ | 42 | * | +-------+---------------+ | 43 | + | +-------+---------------+ | 44 | , | +-------+---------------+ | 45 | - | +-------+---------------+ | 46 | . | +-------+---------------+ | 47 | / | +-------+---------------+ | 48 | 0 | +-------+---------------+ | 49 | 1 | +-------+---------------+ | 50 | 2 | +-------+---------------+ | 51 | 3 | +-------+---------------+ | 52 | 4 | +-------+---------------+ | 53 | 5 | +-------+---------------+ | 54 | 6 | +-------+---------------+ | 55 | 7 | +-------+---------------+ | 56 | 8 | +-------+---------------+ | 57 | 9 | +-------+---------------+ | 58 | : | +-------+---------------+ | 59 | ; | +-------+---------------+ | 60 | < | +-------+---------------+ | 61 | = | +-------+---------------+ | 62 | > | +-------+---------------+ | 63 | ? | +-------+---------------+ | 64 | @ | +-------+---------------+ | 91 | [ | +-------+---------------+ | 92 | \ | +-------+---------------+ | 93 | ] | +-------+---------------+ | 94 | ^ | +-------+---------------+ | 95 | _ | +-------+---------------+ | 96 | ` | +-------+---------------+ | 97 | A | +-------+---------------+ | 98 | B | +-------+---------------+ | 99 | C | +-------+---------------+ | 100 | D | +-------+---------------+ | 101 | E | +-------+---------------+ | 102 | F | +-------+---------------+ | 103 | G | +-------+---------------+ | 104 | H | +-------+---------------+ | 105 | I | +-------+---------------+ | 106 | J | +-------+---------------+ | 107 | K | +-------+---------------+ | 108 | L | +-------+---------------+ | 109 | M | +-------+---------------+ | 110 | N | +-------+---------------+ | 111 | O | +-------+---------------+ | 112 | P | +-------+---------------+ | 113 | Q | +-------+---------------+ | 114 | R | +-------+---------------+ | 115 | S | +-------+---------------+ | 116 | T | +-------+---------------+ | 117 | U | +-------+---------------+ | 118 | V | +-------+---------------+ | 119 | W | +-------+---------------+ | 120 | X | +-------+---------------+ | 121 | Y | +-------+---------------+ | 122 | Z | +-------+---------------+ | 127 | Del | +-------+---------------+ | 256 | Keypad 0 | +-------+---------------+ | 257 | Keypad 1 | +-------+---------------+ | 258 | Keypad 2 | +-------+---------------+ | 259 | Keypad 3 | +-------+---------------+ | 260 | Keypad 4 | +-------+---------------+ | 261 | Keypad 5 | +-------+---------------+ | 262 | Keypad 6 | +-------+---------------+ | 263 | Keypad 7 | +-------+---------------+ | 264 | Keypad 8 | +-------+---------------+ | 265 | Keypad 9 | +-------+---------------+ | 266 | Keypad . | +-------+---------------+ | 267 | Keypad / | +-------+---------------+ | 268 | Keypad * | +-------+---------------+ | 269 | Keypad - | +-------+---------------+ | 270 | Keypad + | +-------+---------------+ | 271 | Keypad ENTER | +-------+---------------+ | 272 | Keypad = | +-------+---------------+ | 273 | Up arrow | +-------+---------------+ | 274 | Down arrow | +-------+---------------+ | 275 | Right arrow | +-------+---------------+ | 276 | Left arrow | +-------+---------------+ | 277 | Insert | +-------+---------------+ | 278 | Home | +-------+---------------+ | 279 | End | +-------+---------------+ | 280 | Page up | +-------+---------------+ | 281 | Page down | +-------+---------------+ | 282 | F1 | +-------+---------------+ | 283 | F2 | +-------+---------------+ | 284 | F3 | +-------+---------------+ | 285 | F4 | +-------+---------------+ | 286 | F5 | +-------+---------------+ | 287 | F6 | +-------+---------------+ | 288 | F7 | +-------+---------------+ | 289 | F8 | +-------+---------------+ | 290 | F9 | +-------+---------------+ | 291 | F10 | +-------+---------------+ | 292 | F11 | +-------+---------------+ | 293 | F12 | +-------+---------------+ | 294 | F13 | +-------+---------------+ | 295 | F14 | +-------+---------------+ | 296 | F15 | +-------+---------------+ | 300 | Num lock | +-------+---------------+ | 301 | Caps lock | +-------+---------------+ | 302 | Scroll lock | +-------+---------------+ | 303 | Right shift | +-------+---------------+ | 304 | Left shift | +-------+---------------+ | 305 | Right control | +-------+---------------+ | 306 | Left control | +-------+---------------+ | 307 | Right Alt | +-------+---------------+ | 308 | Left Alt | +-------+---------------+ | 309 | Right Meta | +-------+---------------+ | 310 | Left Meta | +-------+---------------+ | 311 | Left Windows | +-------+---------------+ | 312 | Right Windows | +-------+---------------+ | 313 | Mode / Alt Gr | +-------+---------------+ | 315 | Help | +-------+---------------+ | 316 | Print screen | +-------+---------------+ | 317 | SysRq | +-------+---------------+ | 318 | Break | +-------+---------------+ | 319 | Menu | +-------+---------------+ | 320 | Power | +-------+---------------+ | 321 | Euro | +-------+---------------+ Acknowledgements This version of ANNE could not have been written without: Ian Collier, who wrote the “xz80" emulator. The Z80 emulator in ANNE is based on the one in xz80. Richard Clayton, who supplied vital information on the interactions between the XBIOS and the hardware. Cliff Lawson, who made the PcW hardware specification public. Richard Fairhurst and Jacob Nevins, who provided hardware information. The many authors of Linux, GNU, gcc, SDL, libpng and libxml. The MICO authors who created the mini-STL. Frank D. Cringle, who wrote the Z80 emulator test suite in YAZE. David Cantrell, for his posting on comp.sys.amstrad.8bit describing the use of PostScript in printer emulation. Matthew Gomez, who suggested some of the colour names in the custom colour menu. Kevin Thacker, who wrote the PCW16 driver for MESS. I haven't used any MESS code, but it helped a lot knowing what hardware was being used. “foz”, for helpful bug reports. Digital Research, the original authors of CP/M, GSX and GEM. Caldera (as it then was; later Lineo), for releasing GEM source under the GPL. Previous versions of JOYCE also owed much to: Marat Fayzullin, who wrote the original Z80 emulation code. However, none of this code now remains in ANNE, because it is not compatible with the GPL. Ian Macdonald, who tested JOYCE for DOS. The authors of DJGPP, GRX20 and DRDOS. Samuel Vincent, the author of the SVAsync library. Martynas Kunigelis, on whose DJGPP keyboard driver I based that of JOYCE for DOS.