JOYCE v2.2.1

John Elliott

Abstract

JOYCE is an Amstrad PCW emulator for UNIX and Windows. 
It emulates the PCW 8000, 9000 and 10 series computers, 
but not the PCW 16; see ANNE for PCW16 emulation.

Table of Contents

Introduction
    Copyright
    What JOYCE does
    What's new?
    Concepts
    Compiling JOYCE
        JOYCE on Mac OS X
    Missing Features
    Internet resources
Setting Up
    Directory organisation
        Under Windows
        Under Unix
    Running JOYCE for the first time
        You will need:
        The JOYCE command
        Adding boot discs
        After copying boot discs
        Reading in other discs
    What if I haven't got 3.5 start-of-day discs? 
    What if I haven't got start-of-day discs at all?
In Use
    What is emulated
    How the disc drives are handled
        Boot discs (also known as start-of-day discs)
        Ejecting a disc
        Command-line options
        Non-floppy discs
    What if the speed is wrong? 
        If JOYCE is too slow
        If JOYCE is too fast
Peripherals in JOYCE
    The keyboard
        CTRL / ALT key swapping
        Delete key swapping
    The Mouse
        AMX mouse 
        Kempston mouse
        Mouse auto-patch
    The disc drives
    The LocoLink interface
        LocoLink to a real computer (requires Linux)
        LocoLink to another emulator
        Socket types and names
The JOYCE Menu
    The Action Menu
    The Debug Menu
    The Disks menu
        The Disc Management menu
    The Settings menu
        General options
        Memory
        Disc drives
        Extra drives
        Matrix printer
        Daisywheel printer
        CEN port and PAR port
        CPS8256
        Joystick
        Keyboard
        Mouse
        Video
        LocoLink
        Save settings
JOYCE Utilites
    CENPORT
    DDJOYCE.PRL
    DOSDIR
    EMULIOS.RSX
    EXPORT
    IMPORT
    JOYCEDRV
    PCKEY
        Notes:
    QUIT
    REDIR
    RTC
    VGA and VGACOM
    XPALETTE
JOYCE utilities (PC hosted)
        MD3 discs and Windows NT / 2000 / XP
        Problems reading floppies on Windows 9x
Recent Changes
For Unix system administrators
Keyboard codes
Acknowledgements
    Previous versions also owed much to:



 Introduction

 Copyright

Copyright 1997,2001-7,2009 John Elliott. Parts 
copyright 1994, 1995 Ian Collier; other parts copyright 
1987, 1999 CalderaThe copyright message in the source files names 
Caldera. Actual ownership of the copyrights has 
probably since passed to DRDOS Inc.
. JOYCE can be distributed freely under the conditions 
of the GNU General Public License (sic) - see the file COPYING.

 What JOYCE does

JOYCE emulates a PCW computer (8000, 9000 or 10 
series). Run it, and your Unix or Windows computer 
becomes a PCW.

 What's new?

 Since v2.1.0

 The underlying libdsk and lib765 libraries have been updated.

 A bug in the Z80 emulation which caused Starglider to 
  hang has been corrected.

 The PCKEY utility (in JOYCE) did not work. It has been repaired.

 Initial support for compiling under MacOS X has been added.

 The ability to present a folder on the host computer 
  as a PCW drive, without any additional PCW software. 
  This is still a very new experimental feature -- use 
  it with caution!

 Native LOGO support has been corrected and should now work.

 Native GSX support has been restored, based on 
  original Digital Research source code. 

 Various bugfixes in the floppy drive emulation.

 JOYCE doesn't hang if Trivial Pursuit is run with the 
  emulated CPS8256 interface attached.

 JOYCE now emulates several joystick models.

 The code has been updated to compile without 
  modification on systems with GCC 3.x and SDL 1.2.6.

 A bug has been fixed in the creation of new .DSK files.

 Garbled text in the boot screen has been fixed.

 The utility .DSKs provided actually contain all the 
  files they should.

 Windows GDI printing was printing at a third of the 
  correct size; this has been corrected.

 Help text corrected if you press F1 on the boot screen.

 The Windows version now works if there are no printers 
  set up on the system.

 Since v2.0.0

 Some internal structural changes. 

 LocoLink can be emulated using the parallel port (only 
  under Linux 2.4 or later), Unix domain sockets, or TCP/IP.

 The built-in printer emulations support direct 
  printing under Windows.

 All the utility programs have been rewritten to 
  cross-build under Unix rather than natively under 
  CP/M. This may introduce some instabilities.

 Since earlier versions

See section [sec: changes]. 

 <sec: concepts>Concepts

When moving from a PCW to an emulator, the biggest 
change you have to accustom yourself to is the way that 
JOYCE handles discs. Real PCWs (except the few with 
add-on hard drives) use real floppy discs; you use a 
start-of-day disc to use LocoScript or MicroDesign, a 
data disc to save your work on, and so on.

It is possible for JOYCE 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

PCW programs can't generally use the PC's hard drive 
directly. For one thing, it's too big; and for another, 
it's not in CP/M formatIf you do happen to have a CP/M partition on your hard 
drive, I don't want to know. JOYCE still won't use it.
. Instead, JOYCE creates one or more "disc image files". 
Each of these is the equivalent of one real PCW disc.

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 JOYCE.

 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 PCW's "A" and "B" 
drives have nothing to do with your PC's real floppy 
drives. The emulated PCW can be happily using a disc in 
its "B" drive even if your PC has only one drive.

Converting your PCW discs to disc image files is 
covered in section [sec: setup].

 Disc image folders

JOYCE 2.1.8 and later can also use folders instead of 
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 instruct the PCW to make ASCII 
files, save them to such a disc/folder, and then read 
them directly with PC software.

 Compiling JOYCE

If you have downloaded JOYCE as a binary for your 
platform (eg: the full Windows install, or an RPM), you 
can skip this section.

To compile JOYCE, you will need:

 SDL, the Simple DirectMedia Layer: 
  <http://www.libsdl.org>. You need version 1.0.8 or later.

 libxml, the xml parser used by GNOME 
  <http://www.libxml.org/>. JOYCE was tested with 
  version 1.8.9.

 libpng, the image library. 
  <http://www.libpng.org/pub/png/>. You need version 
  1.0.6 or later.

You should be able to compile with the following 
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 JOYCE for Windows, you need the 
XMINGW32 cross-compiler pack from 
<http://www.libsdl.org>, and MINGW32 versions of the 
above libraries.

 JOYCE on Mac OS X

I have successfully compiled JOYCE 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 a JOYCE that is still very much a 
UNIX application; there's no application icon, no 
native OS X menu, and so on.

Finally, OS X uses the [f9] and [f10] keys for Expos; 
so you will need to use [Command]+[F9] and 
[Command]+[F10] instead.

 Missing Features

These features were present in JOYCE 1.36 but not in 
the current JOYCE:

 Built-in debugger.

 Internet resources

The latest versions of JOYCE - and any future updates - 
will be downloadable from 
<http://www.seasip.demon.co.uk/Unix/Joyce/>.

Announcements of new JOYCE releases, if any, will be 
made to the newsgroup <news:comp.sys.amstrad.8bit>. It 
is also on-topic to discuss JOYCE in this newsgroup.

 <sec: setup>Setting Up

 Directory organisation

 Under Windows

JOYCE uses 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 JOYCE to put its files in "My Documents"
, then you can override it. In JOYCE, 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 or move the "Joyce" directory from "My Documents"
 to the new directory you specified.

 Under Unix

JOYCE 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 JOYCE for the first time

 You will need:

 A version of JOYCE that installed correctly. 

 A screen capable of 800x600x256 graphics. JOYCE may 
  well be faster in 256 colour mode than in (say) 
  16-bit mode. 

 One of the following: 

   At least one 3.5" PCW start-of-day disc; 

   Disc images of PCW start-of-day discs, that you have 
    previously generated;

   A working JOYCE 1.3x installation.

 The JOYCE command

Under Windows, JOYCE should be run from the Start Menu. 
Under Unix, the command to use is either "xjoyce" (to run 
in a window) or "xjoyce -f" (to run full screen). Other 
command line options are given in section [sec: cmdline].

 <sec: addboot>Adding boot discs

The first time JOYCE is started, it will detect that no 
boot discs have been read in. Unless you want to boot 
laboriously from a floppy every time you use JOYCE, you 
should choose the "set up boot discs properly" option.

If you had a previously working JOYCE installation, 
then this will be detected, and you will be given the 
option to copy boot discs from it. If you decide not to 
to this, you will have to provide start-of-day discs or 
disc image files.

The next menu that appears asks you for the location of 
the boot disc to use. If you are using real floppies, 
then select the correct drive (A: or B:). If you are 
using pre-prepared DSK files, choose the correct file. 

If you are copying a MicroDesign program disc with copy 
protection (or other similar programs such as Tweak3), 
you will also need to click on "Advanced" at this point 
and select the "MicroDesign program disc" option. Note 
that this will not work on stock Windows NT, 2000 or 
XP; see section [sec: md3nt].

Next select "Continue". You will be asked for a name to 
give to this boot disc (eg: "LocoScript" or "CP/M"). 

Once you have entered the name, the disc is read in and 
converted to a JOYCE .DSK file. If you were copying 
from a real disc, you can put it away when the drive 
light goes out; JOYCE won't need it again.

You can then repeat for as many boot discs as you like.

If you have trouble copying boot discs under Windows 
95, 98 or ME, then see section [failread] which describes a 
workaround using PCWTRANS.

 After copying boot discs

The JOYCE opening screen will appear, with up to 9 boot 
discs listed on it. If you read in more than 9, press 
[f3] to see the others. Choose the disc you want to 
use, and the black stripes should start to march down 
the screen.

When you are ready to quit, press [f10].

 Reading in other discs

The JOYCE automatic setup routine only covers 
start-of-day discs. To convert other discs (eg, data 
discs), press [f9] for the JOYCE menu, then [f2] for 
the Discs menu, and select "Disc Management". From the 
menu that appears, choose "Convert floppy to JOYCE DSK file"
. The rest of the procedure is similar to the one for 
boot discs, described in section [sec: addboot].

 What if I haven't got 3.5" start-of-day discs? 

If you have the ability to transfer files to and from 
your PCW (by a serial link or LocoLink, for example) 
and 1Mb of memory (512k for 8000 series PCWs) then you 
can use DU54 to make the disc images. Download DU54 
from my website, and use its "Copy" option to copy from a 
disc to a file in CPCEMU format. Then transfer the 
resulting file to your PC. These files will be bigger 
than the floppies they were copied from; so you need a 
big RAMdrive to put them in.

Once you have the files on the PC in CPCEMU format, 
proceed as described in section [sec: addboot], with pre-prepared 
disc images.

 What if I haven't got start-of-day discs at all?

Let me make this clear: I can not supply copies of 
start-of-day discs. My recommendation would be to buy 
new ones from SD Microsystems; contact sdmicro@aol.com.

 In Use

 What is emulated

 The Z80. 

 2MB of memory.

 The screen. 

 The keyboard. 

 The timer. 

 The PCW8256/8512/9256/10 dot-matrix printer. Unless 
  you have a printer that isn't supported by the PCW 
  (eg: the HP Deskjet 720C) or you are using software 
  such as LocoScript 1 that doesn't support external 
  printers, I recommend that you use the CPS8256 
  printer interface instead.

 The PCW9512/9512+ daisywheel printer. The same caveats 
  apply as for the dot-matrix printer.

 The CPS8256 parallel/serial interface. You can print 
  to a disc file or a UNIX command (eg, "lpr" for direct 
  printer output). Serial ports can be mapped to a file 
  or a device node (eg "/dev/ttyS0" for direct connection 
  to other computers). 

 A Centronics-only printer interface. You can print to 
  a disc file or a UNIX command (eg, "lpr" for direct 
  printer output). Some CP/M versions cannot detect the 
  Centronics interface; in this case, you should 
  disable it and enable the CPS8256 interface instead.

 Most of the floppy disc controller. However, JOYCE has 
  only limited access to the PC's real floppy drive. 

 The mouse (in AMX or Kempston mode). You will need a 
  three-button mouse to use the AMX mode properly - the 
  Microsoft Intellimouse with the scroll wheel is fine. 

 The PCW9512 PAR port.

 The beeper.

 The LocoLink interface.

 <sec: morediscs>How the disc drives are handled

The basic concept of disc image files was described in 
section [sec: concepts]. There are several subtleties to be aware of:

 Boot discs (also known as start-of-day discs)

When JOYCE is started, both disc drives are normally 
empty. As soon as you select which system to boot, the 
disc image you chose (normally named something like 
~/Joyce/Boot/boot1.dsk) will be inserted in the PCW's A 
drive. You can add, remove or rename boot discs using 
the Disc Management menu (press [f9] for the JOYCE 
menu, then [f2] (Disc) and choose "Disc Management").

 Ejecting a disc

To eject a disc, press [f9] for the JOYCE menu, then 
[f2] (Disc). If there is a disc in the PCW's A or B 
drive, you can eject it by selecting the corresponding "eject"
 option. Remember that ejecting discs from JOYCE's 
emulated drives doesn't have anything to do with 
whatever floppy drives are actually fitted to the PC.

 <sec: cmdline>Command-line options

To start JOYCE and make it automatically boot from one 
of the discs on the boot menu, use:

xjoyce -A #n

for example

xjoyce -A #2

will choose option 2 from the boot menu.

If you want JOYCE automatically to run a boot disc file 
(not necessarily one of the ones on the menu), then use 
-A with a filename:

xjoyce -A locoscript3.dsk

will load "locoscript3.dsk". 

If you want to start with a floppy disc in drive B:, 
then use the -B command-line option: 

xjoyce -B /home/fred/Joyce/Disks/diskb.dsk

JOYCE can also start an EMS/EMT file directly. To do 
this, use -E:

xjoyce -E /tmp/j14cpm3.ems

You can add a memory-size option to any of the above 
commands - for example, 

xjoyce -A locoscript140.dsk -m 256

will boot from "locoscript140.dsk" with 256k memory 
(LocoScript 1.40 malfunctions with the default 2Mb).

 Non-floppy discs

 JOYCEDRV.FID gives the emulated PCW a hard drive, 
  and/or direct access to PCW floppy discs. It requires 
  a recent version of CP/M (BIOS 1.8 or later) or 
  LocoScript 2.30 or later. 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 will run under any 
  version of 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 JOYCE environment. They will run under 
  any version of CP/M.

All these utilities are on the file UTILS.DSK. You can 
get at them with a command something like:

xjoyce -B=/usr/local/lib/Joyce/Disks/utils.dsk

and they will appear on drive B:. REDIR.COM and its 
companion programs are in Group 1; the others are in 
Group 0.

 What if the speed is wrong? 

 If JOYCE is too slow

One solution is to increase the CPU speed. Press [f9], 
then [f6] and select 'General'. Then enter the new 
speed; since my original PCW had a Sprinter, I prefer 
to run at 200% speed.

It may also be possible to improve the performance of 
JOYCE 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 that use a mouse pointer may appear a 
little jerky, but JOYCE should run at its full speed.

To change the video refresh frequency, start JOYCE. At 
the opening screen, press [f9], then [f6] and select 
'Video'. Then enter the new frequency and press RETURN.

 If JOYCE is too fast

The built-in speed regulation in JOYCE should stop it 
running too fast. Possibly you could reduce the overall 
speed: press [f9], then [f6] and select 'General'. Then 
enter a new speed.

 Peripherals in JOYCE

 The keyboard

The PC keyboard is laid out a bit differently from the 
PCW keyboard. The following keys have non-obvious 
meanings: 

[This is for a UK keyboard with XFree86. Other X 
servers may behave differently].

+--------------+-----------------+-----------------------------------+
|   PC key     |    PCW key      |               Notes               |
+--------------+-----------------+-----------------------------------+
+--------------+-----------------+-----------------------------------+
|     ESC      |      EXIT       |                                   |
+--------------+-----------------+-----------------------------------+
|     `       |      STOP       | (top left hand corner, under ESC) |
+--------------+-----------------+-----------------------------------+
|     \ |      |  \frac{1}{2} @  |   (down by the left-hand SHIFT)   |
+--------------+-----------------+-----------------------------------+
|     ' @      |       <        |                                   |
+--------------+-----------------+-----------------------------------+
|     # ~      |      # >        |                                   |
+--------------+-----------------+-----------------------------------+
|    CTRL      |     EXTRA       |           (can use ALT)           |
+--------------+-----------------+-----------------------------------+
|     ALT      |      ALT        |          (can use CTRL)           |
+--------------+-----------------+-----------------------------------+
|   WINDOWS    |     EXTRA       |                                   |
+--------------+-----------------+-----------------------------------+
|     F11      |      [+]        |               (Set)               |
+--------------+-----------------+-----------------------------------+
|     F12      |      [-]        |               Clear               |
+--------------+-----------------+-----------------------------------+
| PrintScreen  |      PTR        |                                   |
+--------------+-----------------+-----------------------------------+
|  Keypad *    |      PTR        |                                   |
+--------------+-----------------+-----------------------------------+
|  Keypad -    |      [-]        |               Clear               |
+--------------+-----------------+-----------------------------------+
|  Keypad +    |      [+]        |                Set                |
+--------------+-----------------+-----------------------------------+
|   Delete     |      CAN        |       (numeric keypad "".)        |
+--------------+-----------------+-----------------------------------+
|   Insert     |     RELAY       |       (numeric keypad ""0)        |
+--------------+-----------------+-----------------------------------+
|     End      |   FIND/EXCH     |       (numeric keypad ""1)        |
+--------------+-----------------+-----------------------------------+
|  PageDown    |   UNIT/PARA     |       (numeric keypad ""3)        |
+--------------+-----------------+-----------------------------------+
|    Home      |    LINE/EOL     |       (numeric keypad ""7)        |
+--------------+-----------------+-----------------------------------+
|   PageUp     |   WORD/CHAR     |       (numeric keypad ""9)        |
+--------------+-----------------+-----------------------------------+
|   Insert     |      CUT        |        (under PrintScreen)        |
+--------------+-----------------+-----------------------------------+
|    Home      |      COPY       |        (under ScrollLock)         |
+--------------+-----------------+-----------------------------------+
|   PageUp     |     PASTE       |        (under Pause/Break)        |
+--------------+-----------------+-----------------------------------+
|   Delete     |     DEL->       |          (under Insert)           |
+--------------+-----------------+-----------------------------------+
|     End      |      CAN        |           (under Home)            |
+--------------+-----------------+-----------------------------------+
|  PageDown    |    DOC/PAGE     |          (under PageUp)           |
+--------------+-----------------+-----------------------------------+


This is the full keyboard:

<Graphics file: pcwkey.ps>


If you find these mappings inconvenient, you can use 
PCKEY (on the Utilities disc) to change keyboard mappings.

The keyboard has two user-configurable settings. To set 
them, press [f9] in JOYCE; then [f6] for Settings, and 
choose Keyboard. 

 <sec: keyswap>CTRL / ALT key swapping

There are two ways the CTRL and ALT keys can be set up. 
These are:

 The PC ALT key is used as the PCW ALT key. In this 
  mode the key captions match better than the key positions.

 The PC ALT key is used as the PCW CTRL key. This makes 
  the positions of the keys match better than their captions.

+---------+-------------------+------------------+
| PC key  | PCW key (mode 1)  | PCW key (mode 2) |
+---------+-------------------+------------------+
+---------+-------------------+------------------+
|  ALT    |       ALT         |      EXTRA       |
+---------+-------------------+------------------+
|  CTRL   |      EXTRA        |       ALT        |
+---------+-------------------+------------------+


 <sec: keyswap2>Delete key swapping

In the same way, the Backspace and Delete keys can be 
swapped. You may need to use this, depending how your 
X-Window system is configured.

 The Mouse

There were three major types of PCW mouse:

 AMX

 Kempston

 KeyMouse

JOYCE emulates the first two of these. To choose which 
type is selected, press [f9] in JOYCE; then [f6] for 
Settings, and choose Mouse. 

 <sec: mousetypes>AMX mouse 

The AMX mouse emulation is tuned for MicroDesign 3, 
with the mouse movement option set to "Slow". Most 
programs support the AMX mouse, so this is probably the 
best choice. However, you will need a three-button 
mouse (or one with a scroll wheel) to use it successfully.

 Kempston mouse

The Kempston mouse emulation is designed for Stop 
Press. Fewer programs support the Kempston mouse than 
the AMX, but it doesn't need a three-button mouse.

 <sec: autopatch>Mouse auto-patch

The Mouse Auto-Patch feature (only available with the 
AMX mouse emulation) is used to improve mouse handling 
in PCW programs. When it is switched on, JOYCE will 
attempt to link Microdesign, Stop Press or Masterpaint 
directly to the PC's mouse, bypassing the normal mouse 
driver. If successful, this results in smoother mouse 
performance.

When you start the program that uses the mouse, you 
will see either "No mouse patch applied" (in which case, 
the link could not be established) or "Applied program 
mouse patch" (the link was established). 

 The disc drives

Instead of real disc drives, JOYCE works with "disc 
image files" on the computer's hard drive. These are 
fully described in sections [sec: concepts] and [sec: morediscs].

 The LocoLink interface

JOYCE 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)

 For JOYCE to act as the slave computer, use a LapLink 
  cable (not the original LocoLink cable) to connect 
  the parallel ports of the two computers being linked. 
  Go into the settings for the LocoLink interface, and 
  set it to "Output to parallel port", specifying the 
  name of the parallel port device (eg: /dev/parport0).

 For JOYCE to 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 PAR port, and set it to "Output to parallel port"
  , as above.

 LocoLink to another emulator

 For JOYCE to act as the slave computer, go into the 
  settings for the LocoLink interface and set it to "
  output to Socket". On the screen that appears, select 
  the correct socket type and name (see below) and 
  ensure the "Server (LocoLink slave)" option is ticked.

 For JOYCE to act as the master computer, go into the 
  settings for the PAR 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, JOYCE 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". 

  For a LocoLink slave, the name of the socket is 
  formed "interface:port". The interface is usually 
  either "127.0.0.1" (accept only connections from this 
  computer) or "0.0.0.0" (accept connections from any 
  computer). 

  The port has to be the same on both master and slave 
  sides of the connection, and the host/interface have 
  to refer to the same computer. For two emulators on 
  the same computer, use "127.0.0.1:port" for both master 
  and slave. 

 The JOYCE Menu

If you press [f9] (or the Menu key on a Windows95 
keyboard, or Command+F9 on a Mac OS X system) a menu 
will appear at the top of the screen. It offers the 
following options:

 ESC=Back to JOYCE

Leaves the menu system.

 f1 = Help

Display the keyboard layout onscreen.

 f2 = Discs

Options for floppy drives A: and B:. Use this to 
"insert" and "eject" discs, and to read floppy discs 
into the JOYCE environment. It brings up the Discs menu below.

 f4 = Printer

Control the built-in dot-matrix or daisywheel printer. 
You should not normally need to use this menu; the "
printer control" state (obtained by pressing [*] on the 
numeric keypad or [PrintScreen]) should be able to 
perform the necessary functions.

 f5 = Reboot

Reboot the PCW; equivalent to SHIFT+EXTRA+EXIT. You 
will be asked for confirmation.

 f6 = Settings

Settings for all aspects of the emulator. The Settings 
menu will appear.

 f7 = Dbg

Display the Debug menu ([sec: dbgmenu]). 

 f8 = Action

Display the Action menu ([sub:The-Action-Menu]).

 f10 = Quit

Leave JOYCE. You will be asked for confirmation. Under 
Mac OS X, [f10] is used by Expos so use Command+F10.

 <sub:The-Action-Menu>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. It 
can also be used if you run DISCKIT while in the 
800x600 screen mode; DISCKIT always sends its output to 
the original PCW screen.

 <sec: dbgmenu>The Debug Menu

There are three options here, intended mainly for 
advanced users or JOYCE developers. 

 "CPU state" displays the values of the Z80 registers and 
  the memory paging.

 "Debug mode" displays the debug console, on which system 
  messages will appearIn previous versions, JOYCE had a built-in debugger 
that ran in the debug console. This is not present in 
JOYCE v1.9.0.
  .

 "RAM dump" writes out the bottom 256k of memory to a 
  file in the current directory called "joyce.ram". This 
  is not a full snapshot facility; memory dumps can't 
  be reloaded, and they don't contain CPU state.

 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 ask to "insert" a folder, and the 
  folder you select has not previously been used in 
  this way by JOYCE, 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 five options:

 Add a boot disc - Reads in a start-of-day disc and 
  adds it to the opening menu.

 Rename a boot disc - Allows you to change the caption 
  associated with a start-of-day disc.

 Delete a boot disc - Removes a start-of-day disc from 
  the opening menu. Use this option with caution!

 Convert floppy to JOYCE .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. It's 
safest to change JOYCE settings while the opening menu 
is on the screen - after all, you wouldn't plug an 
interface into a real PCW with the power on, would you?

 <sec: genopt>General options

This screen allows you to choose which PCW model to 
emulate, and how fast it should appear to be. Some 
points to note are:

 JOYCE knows the difference between boot discs for 
  dot-matrix PCWs (8256, 8512, 9256, 10) and daisywheel 
  PCWs (9512, 9512+). If you have selected a PCW model 
  that doesn't match the boot disc, JOYCE selects the 
  closest equivalent when booting.

 JOYCE treats the PCW8256 and PCW8512 as one choice, 
  since the only difference is the number of disc 
  drives and the memory size, both of which can be 
  configured in other menus.

 JOYCE also treats the PCW9256 and the PCW10 as one 
  choice. The differences between these models are the 
  memory size and the presence of a Centronics port, 
  both of which are configurable in other menus.

 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. 

If you are running a very old version of CP/M, you may 
need to reduce memory to 512k to get DISCKIT to run. 
Some LocoScript 1 versions also malfunction if there's 
more than 512k of memory.

 Disc drives

Note: The menus in this section only allows you to 
create configurations that could exist on a real PCW. 
By manually editing ~/Joyce/joycehw.xml, you can create "
impossible" configurations, such as a system with three 
floppy drives (CP/M and LocoScript won't detect the 
third one.) If the configuration is "impossible", the 
menus will look different as they attempt to 
accommodate the changes.

The settings in this menu are:

 Boot discs are read-write / read-only: 

This sets whether JOYCE makes emulated boot discs 
write-protected. Note that early CP/M releases (such as 
the 1.4 BIOS issued with 8000 series PCWs) need to have 
a change made to SUBMIT.COMHere's a transcript of a SID session making the 
necessary change:

A>SID SUBMIT.COM

CP/M 3 SID - Version 3.0

NEXT MSZE  PC  END

1600 1600 0100 DAFF

#S3A6

03A6 CD 3E

03A7 E4 0D

03A8 03 00

03A9 32 .

#W

002Ah record(s) written.

#G0
 before they can boot from write-protected disc images.

To override this for a particular boot disc, press [f9] 
while the loading stripes are on the screen; then press 
[f2] and change the setting.

 Controller type (8256/8512/9512 vs. 9256/9512+/10) 

You should set the correct controller type to match 
your system discs. At least some versions of Locoscript 
3 for the PCW9256 refuse to load unless the controller 
type is also set to 9256. This option is also set by 
the "PCW model" setting in the general options screen.

 Drive A: settings / Drive B: settings: 

This brings up its own menu, allowing you to set what 
type of disc drive is attached to the PCW. The three 
standard types are those supplied as standard with 
PCWs. If you want to emulate 5.25" drives or anything 
else unusual, select "other" and manually enter the drive 
type, the number of cylindersThe 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.

To emulate a single-drive PCW, set the type of drive B: 
to "Not connected".

 <sec: extradrv>Extra drives

This menu allows you to set up drives C: - L: and N: - 
P:. Obviously these drives don't exist on real PCWs, 
but they can on a JOYCE system, provided you are using 
a recent version of CP/M (1.12 / 2.12 or later) or 
LocoScript (2.50 or later). You will need to have a 
copy of JOYCEDRV.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: and B: drives.

 As a hard drive with 8Mb of storage. The hard drive 
  will also be stored on a .DSK file (or in a folder, 
  depending which option you chose), 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 or folder  | .DSK file or folder  | floppy drive  |
+---------------------------------------------------+----------------------+---------------+
|  Hard drive using special image file or folder    | .DSK file or folder  |  hard drive   |
+---------------------------------------------------+----------------------+---------------+


 Matrix printer

The dot-matrix printer menu offers the following settings:

 Connected/Disconnected: Is the printer plugged in or 
  not? 

 Paper size: There are a number of standard paper 
  sizes; or you can enter your own using "Custom".

 Output format: PostScript or PNG. PNG output produces 
  a small graphic file (around 20k) per page, while 
  PostScript output produces one vast file (we're 
  talking 6Mb per page) containing all the output from 
  a JOYCE session. Note that although the PNG files 
  produced are small in size, they are big in area. 
  Under Windows, there is also a "Use Windows' GDI" 
  option, which sends output to the default Windows printer.

 Output to Directory: PNG output goes to disc files 
  called "matrix0.png", "matrix1.png" etc., while 
  PostScript output goes to "matrix0.ps", "matrix1.ps"... 
  The directories used are ~/Joyce/Pngs and ~/Joyce/PS 
  respectively.

 Output to UNIX command: Output goes to a Unix 
  pipeline. You can use this to send output to the Unix 
  printing system. It is recommended to use PostScript 
  output for this. Note that printing will usually only 
  start when JOYCE shuts down.

 Daisywheel printer

The daisywheel printer menu offers the following settings:

 Connected/Disconnected: Is the printer plugged in or 
  not? Note that unlike on a real PCW, disconnecting 
  the daisywheel with the computer turned on does not 
  damage the memory chips!

 Output format: Windows only. You can choose between 
  PostScript (each session produces a single .ps file) 
  or "Use Windows' GDI", which sends output to the 
  default Windows printer.

 Paper size: There are a number of standard paper 
  sizes; or you can enter your own using "Custom".

 Output to Directory: The output is in PostScript 
  format, and is sent to "daisy0.ps", "daisy1.ps", etc. in 
  the directory ~/Joyce/PS.

 Output to UNIX command: Output goes to a Unix 
  pipeline. You can use this to send output to the Unix 
  printing system. Note that printing will usually only 
  start when JOYCE shuts down.

 CEN port and PAR port

The following settings are available for the CEN port 
and the PAR port:

 Connected/Disconnected: Is the appropriate interface 
  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 : The port is directly mapped 
  to one of the computer's parallel ports 
  (/dev/parport0, /dev/parport1, etc.) This allows the 
  port to act as a LocoLink master when connected to a 
  real PCW.

 Output to socket: Output is sent to another process or 
  computer, over a socket. This allows the port to act 
  as a LocoLink master in conjunction with another 
  instance of JOYCE.

 Under Windows, you also get the option to send data 
  directly to LPT ports. 

 CPS8256

There are three configuration screens available for the 
CPS8256. The first one has the following settings:

 Connected/Disconnected: Is the CPS8256 interface 
  connected to the PCW?

 Parallel port: Brings up the same settings screen as 
  for the standalone CEN port, to configure output.

 Serial port: Displays the filenames used for serial 
  input and output. These can both be set to a device 
  special file (eg: "/dev/ttyS0") for direct access to 
  serial ports. Under Windows COM1: to COM4: can be chosen.

 Joystick

This allows a real joystick on the computer to simulate 
an add-on joystick for the PCW. The first part of the 
menu is used to select what PCW interface is being 
emulated - Kempston, Spectravideo or Cascade. Note that 
the Spectravideo and Cascade interfaces conflict with 
the CPS8256 serial interface; don't try to use both at 
the same time. 

Once you have set the joystick type, select the second 
option to choose which joystick on the host system 
should be connected to the emulated interface.

 Keyboard

The keyboard settings screen has two options. One 
controls which way round the CTRL and ALT keys are 
mapped (see section [sec: keyswap]) and the other controls which way 
round the DELETE keys are (see section [sec: keyswap2]).

There are also two joystick options. These relate to a 
curious little piece of history. The controllers in all 
PCW keyboards include joystick support; but there's no 
joystick socket for them to plug in to (compare the 
PC1512 keyboard, where there is a joystick socket). 
Strictly in the interests of completeness, JOYCE 
provides the joystick sockets. To activate one or the 
other, select "Joystick 1" or "Joystick 2". A menu appears 
listing the joysticks on the host computer; select the 
one to use. To the best of my knowledge no PCW software 
supports the keyboard joystick; use one of the other 
joystick models to to get something useful done.

 Mouse

Two mouse settings are available here:

 Emulation mode: No mouse, AMX mouse, or Kempston mouse 
  (see section [sec: mousetypes]).

 Auto patch on or off (see section [sec: autopatch]).

 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 JOYCE is 12Hz, which is fine 
  for nearly all programs; even at 3.75Hz CP/M and 
  LocoScript work fine.

 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").

 You can also choose whether to have a green screen 
  (8000 series), white screen (9000 series) or any 
  other screen colours here.

 LocoLink

The LocoLink settings allow you to set whether or not a 
LocoLink interface is connected. If it is, then you get 
the same options as for a parallel port. However, only "
Output to Parallel port" and "Output to socket" can be 
used for a LocoLink connection.

 Use "Output to Parallel port" to act as the LocoLink 
  slave when the "master" computer is a real PC. Connect 
  the parallel ports together with a LapLink cable.

 Use "Output to socket" to act as the LocoLink slave when 
  the "master" is an emulated computer. 

 Save settings

If you do not save the settings, they will remain in 
force only for the duration of your current JOYCE 
session. The settings will be saved to the file 
Joyce/joycehw.xml in your home directory.

 JOYCE Utilites

The following utility programs are supplied with JOYCE. 
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 "utils.dsk".

 CENPORT

CENPORT is a fast driver for the standalone Centronics 
printer port. Just type:

CENPORT

and printer output will be sent to the destination 
defined for that port. Any DEVICE setting for the 
printer will be ignored.

CENPORT only works under CP/M. LocoScript 1 cannot 
print from JOYCE (except using the emulated dot-matrix 
printer). If LocoScript 2 and later do not detect the 
Centronics port, use the CPS8256 printer port instead. 

 DDJOYCE.PRL

DDJOYCE is a GSX driver for the host PC's graphics 
screen, allowing high-resolution colour graphics to be 
used from CP/M. It requires JOYCE 2.1.7 or later.

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:

 DR Graph works correctly, but when it shuts down the 
  screen goes blank. This is because DR Graph does not 
  make a proper 'close workstation' call when it 
  closes. Use the Action menu (section [sub:The-Action-Menu]) to switch back 
  to the PCW 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. This was buggy in JOYCE 2.0.0-2.1.6, but has 
now been corrected.



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.

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.

 <sec: joycedrv>JOYCEDRV

JOYCEDRV.FID is a file which is used to add one or more 
extra disc drives to CP/M (v1.12/2.12+) or LocoScript 
(v2.30+) running within JOYCE. 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.

How many drives you get depends on your environment, 
but on my system I get five under CP/M (C:,D:,E:,F:,and 
G:), and thirteen under LocoScript (C: to L: and N: to P:).

To enable JOYCEDRV, copy the file JOYCEDRV.FID to your 
start-of-day disc image. For example:

 Start JOYCE.

 Select CP/M from the boot menu.

 When the A> prompt appears, press [f9], then [f2] 
  (Disc), then choose the "Insert" option for drive B:. 
  Click on "disc file".

 In the file chooser that appears, click "System disc files"
  , then "utils.dsk". Then click OK.

 Back in the f2=Disc menu, choose "EXIT". Then press ESC 
  to leave the menu system.

 Back at the CP/M prompt, type PIP A:=B:JOYCEDRV.FID

 Press [f9], then [f5] to reboot, and confirm this.

 Select CP/M from the boot menu.

 JOYCEDRV should now list available drives. If not, 
  then your version of CP/M is too old.

If you try to use a disc image that JOYCEDRV cannot 
understand, you will not be able to access it. Under 
CP/M, you will get an "invalid drive" error; under 
LocoScript, you will get a "FID error".

 PCKEY

Syntax: 

PCKEY keyfile

or: 

PCKEY keyfile fidfile

PCKEY is used to alter the mapping of PC keys to PCW 
keys. You may need to use this utility if your keyboard 
does not have a UK layout, or you are using a laptop 
where some keys are difficult to get at. This was buggy 
in JOYCE 2.0.0-2.1.9, but has now been corrected.

When PCKEY is given one parameter, it will read the 
keyfile and make the changes immediately. When it is 
given two, it will compile the keyfile into a .FID 
file, which can then be put on a start-of-day disc and 
which will make the necessary assignments every time 
JOYCE is started.

The format of the keyfile is a series of lines; each 
line reads:

pc-number  modifier  pcw-number  {comment}

  pc-number is the number of the key. For a full 
  listing, see Appendix [keycodes].

  NOTE: These numbers changed between SDL 0.8 and SDL 
  0.10; so if you are upgrading JOYCE from a version 
  which used SDL 0.8, you need to rewrite your PCKEY files.

  modifier must be N, for compatibility with the old 
  DOS version of JOYCE.

  pcw-number is the PCW key number. These are listed in 
  the PCW manual.

So, a typical line might read:

 

27 N 8  ESC goes to EXIT

 

 Notes:

 The key mapping you have set remains until you exit JOYCE.

 The option in the Settings menu to swap CTRL/ALT and 
  Backspace/Delete uses the same method as PCKEY. It is 
  probably best not to map these four keys.

 Key 256 brings up the JOYCE menu. Key 257 brings up 
  the Exit Confirmation screen.

 If you use VGACOM to switch into VGA mode, note that 
  keys set up by PCKEY don't affect the keyboard in VGA mode.

 QUIT

Syntax: 

QUIT { number } { [O] }

QUIT will exit JOYCE. 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 JOYCE 
should return. If there is no number parameter, JOYCE 
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.

 RTC

  Syntax: 

RTC 

or 

RTC [C]

RTC reads the PC's built-in clock. It can be used in 
two ways.

  RTC by itself will set the PCW's clock from the PC's 
  clock. The timing of the PCW's clock will then depend 
  on the speed of emulation, which is another way of 
  saying that it will gradually diverge from the PC's clock.

  RTC [C] links the PCW's clock to the PC's clock; it 
  will be set to the correct time whenever CP/M reads it.

 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.

If you run DISCKIT or a graphical program like Stop 
Press, you will find that no output is visible; use the 
Action menu (section [sub:The-Action-Menu]) to switch back to the native PCW 
screen. 

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.

 XPALETTE

Syntax: 

XPALETTE b f

or: 

XPALETTE br bg bb fr fg fb

XPALETTE takes advantage of the colours on a VGA screen 
to allow the PCW to display in any colour scheme, not 
just black and white. 

The version with two parameters works the same way as 
on a CPC or a Spectrum +3 (though neither of these has 
as many colours as JOYCE has). For example, on a CPC 
you might type:

PALETTE 2 63

to get white text on a blue background. So, in JOYCE, type

XPALETTE 2 63

and the screen colours obediently change.

The version with six parameters allows any colour in 
the 24-bit range to be selected, rather than just 64. 
Instead of a colour being represented by one number, it 
is represented by three:

XPALETTE 0 0 32 255 255 251

will give you a very dark blue background and a 
foreground with the slightest tinge of yellow.

XPALETTE does not mind how the numbers are separated 
(with commas, spaces, *s or whatever) and accepts Hex 
numbers preceded with & (128 = &80 etc.).

Note! Unlike PALETTE 0 0, XPALETTE 0 0 really does 
select black on black. This is not recommended.

 JOYCE utilities (PC hosted)

If you don't want to use JOYCE's own methods for 
converting between disc files and image files, you can 
also use the dsktrans program, which is installed with JOYCE.

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.

To copy a MicroDesign 3 protected disc with DSKTRANS, 
add "-md3" to the end of the command line. 

 <sec: md3nt>MD3 discs and Windows NT / 2000 / XP

Windows NT, 2000 and XP will flat-out refuse to read 
MicroDesign 3 program discs, owing to the copy 
protection used on them. If you are using Windows 2000 
or XP, then it is possible to install Simon Owen's 
floppy disc driver <http://simonowen.com/fdrawcmd/>. In 
this case, select the "Alternative floppy" option as well 
as choosing "MicroDesign program disc".

If you are using Windows NT, or if you don't have the 
correct driver installed, there is no way to make JOYCE 
capable of reading MD3 discs. You will need to:

 Create a bootable DOS floppy disc. If you're on a 
  system which can't do this, then you may be able to 
  get hold of one at www.bootdisk.com. If you only have 
  one floppy drive, the boot disc needs to include a 
  RAM drive at least 1Mb in size. 

 Copy MD3TRANS.EXE to the DOS disc.

 Boot from the DOS disc.

 If you have two drives: Insert the MD3 disc in drive 
  B: and type

MD3TRANS B: A:dskfile

 If you have one drive: Copy MD3TRANS to the RAM drive

COPY MD3TRANS.EXE C:

  then insert your MD3 disc and run MD3TRANS

C:MD3TRANS A: C:dskfile

then insert your boot disc and copy the resulting file back.

COPY C:dskfile A:

Either way, MD3TRANS will produce some error messages 
when copying the protected track. Answer 'I'gnore to 
any error messages that might appear. 

 <failread>Problems reading floppies on Windows 9x

On some versions of Windows 95, 98 or ME, JOYCE has 
trouble creating disc image files. The transfer appears 
to work, but runs very very slowly; and the resulting 
.DSK file is blank.

To get round this:

 Open a DOS prompt.

 Change to the drive and directory holding JOYCE - eg:

C:\WINDOWS>CD "\Program Files\JOYCE"

C:\Program Files\JOYCE>

 Use a PCWTRANS command to read the discs:

PCWTRANS x: dskfile

 When adding the disks to JOYCE, browse to the .DSK 
  file that was just created rather than choosing a 
  real drive.

 <sec: changes>Recent Changes

 New in v2.2.1:

 Updated to the latest LibDsk and Lib765.

 New in v2.2.0:

 Minor code cleanups only.

 New in v2.1.11:

 Corrected a Z80 emulation bug that caused Starglider 
  to hang.

 The CPU state shown in the debugger now includes 
  memory paging status.

 The JOYCE memory dump saves 256k rather than 160k.

 In the file browser you can choose 'Current directory' 
  as well as JOYCE's default directories.

 New in v2.1.10:

 Restored the functioning of the PCKEY utility.

 New in v2.1.9:

 Various changes to improve performance and allow 
  building on Mac 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:

 Finally reinstated the native GSX driver, using 
  Digital Research GEM code released under the GPL.

 Got the native LOGO driver working again; it hadn't 
  worked properly since the port from DOS.

 Added 'Select PCW screen' command.

 Added "Extended .DSK" and "Alternative floppy" to the 
  Drive Type menu.

 New in v2.1.6:

 Bug fix: JOYCE does not crash if run on a Windows 
  system with no printers set up.

 Fixed a bug where writes to DSK files would fail with 
  mysterious errors.

 Added compatibility for DSK files which have both 512 
  byte and 1k sectors.

 JOYCE doesn't hang if Trivial Pursuit is run with the 
  emulated CPS8256 interface attached.

 New in v2.1.5:

 Joystick support.

 Compiles under SDL 1.2.6

 New in v2.1.3, 2.1.4:

 Minor bug fixes.

 New in v2.1.2:

 Bug fix in creation of hard drive .DSK files.

 Compiles without modification under gcc 3.2 (if 
  configured with the --with-stl option).

 New in v2.1.1:

 Bug fixes in the 2.1.x boot ROM and utilities.

 Scale of the Windows GDI output corrected for PCW9512 printing.

 New in v2.1.0:

 Internal restructuring - part of the creation of ANNE.

 LocoLink emulation.

 Support for printing to a Windows GDI printer.

 New in v2.0.1:

 Fixed a bug parsing JOYCEHW.XML.

 New in v1.9.9:

 Windows serial port emulation is now usable.

 New in v1.9.5:

 Windows serial port emulation improved, though it 
  still isn't very good.

 Custom screen colours can be set through the menu system.

 New in v1.9.4:

 Dot-matrix printer output can now be in PostScript 
  format rather than PNG.

 Daisywheel emulation added.

 Bug fixes in the 100x36 text screen (as provided by 
  VGA.FID / VGACOM.COM)

 Partial and buggy serial port support under Windows.

 Floppy controller emulation changed so that .DSK files 
  can be created and formatted.

 New in v1.9.3:

 JOYCE can now read MicroDesign 3 discs (except on 
  Windows NT / 2000 / XP). 

 It is possible to map the PCW's floppy drives directly 
  to the PC's floppy drives. 

 Bug fix: The keypad minus key now correctly maps to 
  the PCW "[-]" key.

 Bug fix: No DirectSound crash when JOYCE terminates on Win95.

 New in v1.9.2:

 It is now possible to set the PCW memory size at 
  startup with the "-m" option.

 Sound output added.

Bug fixes:

 Fix for incorrect colours on some Windows systems.

 The file chooser now works properly in the Windows version.

 New in v1.9.1:

Windows version created.

 New in v1.9.0: 

 JOYCE has been thoroughly overhauled and rewritten in 
  C++. 

 TIMINGS.COM is no longer necessary. The speed of JOYCE 
  is now set using the "General" option from the [f6] 
  settings menu.

 The menu system is entirely new. 

 CPS8256 emulation has been added.

 Dot-matrix printer emulation has been added.

 The disc controller emulation has been rewritten from 
  scratch. It should support disc image files in the 
  CPCEMU "extended" format.

 The Z80 emulation is now Ian Collier's code from xz80.

 The AMX and Kempston mouse emulation are now much more 
  usable, even without the auto-patch mode.

 

 <sec: admins>For Unix system administrators

First and foremost, don't run JOYCE as the root user! 
JOYCE gives the PCW programs within it various methods 
to access the host filesystem; it is entirely possible 
that a malicious PCW program running within JOYCE could 
damage important Unix files. 

It is possible to set up a system-wide installation of 
JOYCE 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: joycehw.xml

 From ~user/Joyce/Boot to /usr/local/share/Joyce/Boot: 
  boot*.dsk and joycebt.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.

 <keycodes>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 (OS X: Command) |
+-------+----------------------------+
| 310   | Left Meta (OS X: Command)  |
+-------+----------------------------+
| 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 JOYCE could not have been written without:

 Ian Collier, who wrote the "xz80" emulator. The Z80 
  emulator in JOYCE 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.

 Digital Research, the original authors of CP/M, GEM 
  and GSX.

 Caldera (as was; it later ended up as Lineo), for 
  releasing GEM under the GPL.

 Everyone who over the years has spared the time to 
  contact me about JOYCE, in particular those who found 
  incompatibilities in the emulation.

 Previous versions also owed much to:

 Marat Fayzullin, who wrote the original Z80 emulation 
  code. However, none of this code now remains in 
  JOYCE, 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.
