           
   
  
  
                       --=-=========================-=--
                            PC-DRAGON 6809 EMULATOR
                       --=-=========================-=--
                                       
                                       
                                       
                                 Version 2.01
                                       
                               Reference Manual
                                       
                                Copyright 1994
                                       
                                By PAUL BURGIN
                                       
                                       
                                       
                                       
                                       
                               Table Of Contents
                                       
                                       
       1    INTRODUCTION                                             5
       
       1.1  EMULATOR OVERVIEW                                        5
       
       1.2  FILES IN THE ARCHIVE                                     6
       
       1.3  OPERATIONAL REQUIREMENTS                                 6
       
       2    PC-DRAGON EMULATOR                                       8
       
       2.1  BASIC OPERATION                                          8
       
       2.2  DIALOGUE BOXES                                           8
       
            2.2.1 GENERAL FUNCTIONALITY                              8
            
            2.2.2 MENUS AND OPTION MENUS                             9
            
            2.2.3 INPUT BOXES                                        9
            
            2.2.4 NUMERIC INPUT BOXES                                9
            
       2.3  FILENAME ENTRY                                           9
       
       2.4  EMULATION OF HARDWARE AND PERIPHERALS                   10
       
            2.4.1 KEYBOARD                                          10
            
            2.4.2 VIDEO                                             12
            
            2.4.3 CASSETTE PORT                                     12
            
            2.4.4 PRINTER PORT                                      13
            
            2.4.5 JOYSTICK PORT                                     14
            
            2.4.6 CARTRIDGE PORT                                    14
            
       2.5  EMULATOR OPTIONS AND MENUS                              15
       
            2.5.1 HELP SCREEN                                       15
            
            2.5.2 TEXT VIEWER MENU                                  15
            
            2.5.3 FILE MANAGEMENT MENU                              15
            
            2.5.4 OPTIONS MENU                                      15
            
            2.5.5 VIDEO MODE MENU                                   16
            
            2.5.6 FUNCTION KEY CONFIGURATION                        17
            
            2.5.7 CONTROL MENU                                      17
            
            2.5.8 ASSEMBLER MENU                                    17
            
            2.5.9 INFORMATION AND CONFIGURATION SCREEN              17
            
       2.6  PROGRAM DEVELOPMENT TOOLS                               18
       
            2.6.1 INTEGRATION OF THE EMULATOR WITH AN ASSEMBLER     18
            
            2.6.2 BUILT-IN DEBUGGER                                 18
            
            2.6.3 EMULATOR SERVICES                                 20
            
       2.7  ADDITIONAL INFORMATION                                  22
       
            2.7.1 VIDEO REFRESH INTERRUPT                           22
            
            2.7.2 ILLEGAL AND UNDOCUMENTED INSTRUCTIONS             22
            
            2.7.3 SNAPSHOTS                                         22
            
            2.7.4 BOOTUP SNAPSHOTS                                  24
            
            2.7.5 SWAPPING                                          24
            
            2.7.6 FUNCTION KEY ASSIGNMENTS                          24
            
            2.7.7 CHANGING EMULATOR COLOURS FROM THE COMMAND LINE   25
            
            2.7.8 CASSETTE FILES                                    25
            
       3    FILE TRANSFER                                           27
       
       3.1  OVERVIEW                                                27
       
       3.2  DRAGON CONVERT                                          27
       
            3.2.1 EXTRACTING FILES FROM SAMPLED CASSETTES           28
            
            3.2.2 CONVERTING OTHER FILE TYPES                       29
            
            3.2.3 CONVERTING FILES FROM CASSETTE FORMAT             29
            
       3.3  COPYCAS UTILITY                                         30
       
       3.4  WHATIS UTILITY                                          30
       
       3.5  READVOC UTILITY                                         30
       
       3.6  HOW TO TRANSFER YOUR ROM                                31
       
       4    EPILOGUE                                                33
       
       4.1  STANDARD DISCLAIMER                                     33
       
       4.2  HOW TO CONTACT THE AUTHOR                               33
       
       4.3  HOW AND WHY YOU SHOULD REGISTER                         33
       
       4.4  THE COCO2 EMULATOR                                      34
       
       4.5  THE NATIONAL DRAGON USERS GROUP                         34
       
       4.6  DRAGON E-MAIL LIST                                      34
       
       4.7  ACKNOWLEDGEMENTS                                        35
       
       4.8  LEGAL BITS AND PIECES                                   35
       
       5    APPENDICES                                              36
       
       5.1  APPENDIX A: TABLE OF EMULATOR SERVICES                  36
       
       5.2  APPENDIX B: TABLE OF CONFIGURABLE COLOURS               40
       
       5.3  APPENDIX C: DEFAULT FUNCTION STRINGS                    41


 
 1    INTRODUCTION
 
 
 
 1.1   Emulator Overview
       
 Welcome to PC-Dragon version 2. This program is a Dragon 32, Dragon  64  and
 Tandy  CoCo  II emulator for IBM PCs and compatibles. It emulates  the  base
 6809  microprocessor and many associated peripherals, enabling  you  to  use
 Dragon and CoCo software on your PC.
 
 PC-Dragon  emulates  all documented 6809 features  and  in  addition  a  few
 undocumented characteristics are supported. Also emulated are the  interrupt
 mechanism, the VDG refresh signal, the Dragon or CoCo keyboard, and printer,
 cassette  and joystick ports. Text mode is emulated using the PC  40  column
 text mode, and all 56 graphics modes are implemented. Optional emulation  of
 artifacted colours is available in monochrome graphics modes.
 
 The  emulator  also features a powerful built-in disassembler and  debugger,
 and integrated support for the freeware Motorola 6809 assembler. There is an
 auto-repeat  buffer  and many emulation options. These include  configurable
 text  and  graphics  colours,  variable interrupt  rates,  and  programmable
 function keys. A range of `services' allow a Dragon programmer to access the
 emulator environment and options from within BASIC or machine code programs.
 
 The emulator supports a number of file types for transferring information to
 and   from  the  emulated  machine.  There  are  snapshot  facilities  fully
 compatible with Jeff Vavasour's CoCo2 emulator versions 1.2 to 1.4, as  well
 as  facilities  to  use files in cassette, cartridge, screenshot,  ROM,  and
 Motorola S-record format. By making use of the Dragon Convert utility, files
 in  Q-Basic,  Dragon-DOS, digital audio and raw binary format  may  also  be
 converted  to  PC-Dragon  compatible files. This  enables  you  to  transfer
 cassette  software  to  the  PC  if you have a  SoundBlaster  Pro  card  (or
 equivalent). A utility is also included which can read Dragon cassettes  via
 the PC parallel port (this requires a special cable).
 
 To use PC-Dragon you must supply a valid ROM image file taken from a genuine
 Dragon  or  Tandy CoCo. The emulator will then detect which of the supported
 architectures  to emulate and provide a PC implementation of  that  machine.
 Note  that  the different architectures each have different RAM requirements
 and  emulation speeds. Dragon 32 emulation, for example, requires  48K  less
 memory  than Dragon 64 emulation and also performs approximately 30% faster.
 If  you  have  more  than  one  ROM image you may  also  choose  a  specific
 architecture using the available command line switches (/32, /64 or /T).
 
 If  you have obtained PC-Dragon from a bulletin board or FTP server then you
 should  not  have  received a ROM image with this package  (for  reasons  of
 copyright). However, a number of methods for transferring the ROM from  your
 real  machine  to  your PC are suggested in section 3.6  of  this  reference
 manual.
 
 This  documentation  refers in general to the `Dragon'  to  mean  either  of
 Dragon  32,  Dragon  64 or Tandy CoCo II. It explicitly mentions  a  machine
 where the architectural differences are significant.
 
 
 
 1.2   Files In The Archive
       
 The emulator archive consists of the following files:
 
   DRAGON.EXE      PC-Dragon emulator.
   PCDRAGON.ICO    Icon file for use with Windows 3.x.
   FILE_ID.DIZ     A short archive description used by bulletin boards.
   
   DC.EXE          Multi-purpose file conversion utility.
   COPYCAS.EXE     A utility to make renamed copies of cassette files.
   WHATIS.EXE      A utility to extract information from various files.
   READVOC.COM     A utility to sample cassettes via the PC parallel port.
   
   ROM_STUB.DGN    A header file for raw ROM images.
   
   PCDRAGON.PS     PC-Dragon reference manual in postscript (41 pages).
   PCDRAGON.TXT    Reference manual converted to plain text format.
   WHATSNEW.201    List of changes for PC-Dragon version 2.01.
 
 The following example snapshot files are also included:
                   
   BOOTSNAP.***    These files allow the emulator to initialise quickly.
   DIAGRAM.***     Circuit diagram for the parallel cassette interface cable.
   TETRAS.D96      Previously unreleased Dragon 32/64 arcade game.
   SHANGHAI.D96    Dragon 32/64 oriental patience game.
                   
 The  source  code  for  the emulator can be found in  the  SOURCE  directory
 (registered version only).
 
 READVOC.COM  and the DIAGRAM files are included with permission from  Gerton
 Lunter.  All other programs, including the example files, are the sole  work
 of  the author. The unrestricted distribution status applies to all programs
 in the archive, however this status is only granted as a collective package.
 Please remember that if you like PC-Dragon and use it regularly then you are
 encouraged  to  register.  All proceeds from registrations  are  donated  to
 charity; please see section 4.3 for registration details.
 
 
 
 1.3   Operational Requirements
       
 PC-Dragon  runs  on  any  PC with EGA graphics and MS-DOS  3.0  (or  above).
 However,  at  least a 40MHz 386 is recommended because the emulator  is  not
 very  fast  (expect only 40% of the real speed when using a  486DX-33).  The
 emulator  can  be run full screen under MS-Windows 3.x or in a  DOS  box  if
 Dragon  graphics modes are not required. Similarly, non-EGA video cards  may
 be used if graphics modes are not required.
 
 The emulator requires up to 310K of base memory, and may also swap memory to
 disk  for  selected operations. It is possible to run PC-Dragon from  either
 floppy  or  hard disk but initialisation is considerably slower from  floppy
 disk.  The  TextView  pager is also very slow when used  with  slow  drives,
 because it operates on the text entirely from disk.
 
 A  Microsoft  or  Mouse Systems compatible mouse may be  used  for  joystick
 emulation  and  mouse support services. A PC joystick may also  be  used  to
 emulate the Dragon joysticks.
 
 To read and write Dragon cassette programs using the Dragon Convert utility,
 sampling  software  and a SoundBlaster Pro sound card  (or  equivalent)  are
 required.  A  sound  card  is not required to read  Dragon  cassettes  using
 ReadVoc,  but a special cable must be constructed (the circuit  diagram  for
 this cable is included).
 
 The  freeware  Motorola  6809  assembler AS9.EXE  is  required  to  use  the
 Integrated  Development Environment (IDE) features  of  the  emulator.  This
 assembler  is  available  from several FTP sites including  SimTel  and  its
 mirror sites (eg. src.doc.ic.ac.uk). Look for filename `motoasms.zip' in the
 `crossasm' directory.
 
 PC-Dragon  can  be  run  under the Acorn Archimedes 80188  PC  emulator  but
 execution  is very slow indeed. The Amiga PC-Task emulator is not compatible
 with PC-Dragon.
 
 
 
 2     PC-Dragon Emulator
 
 
 
 2.1   Basic Operation
       
 The emulator should be run by typing `DRAGON' together with any command line
 options  that you require. You can also give the names of up to two snapshot
 or  cartridge  files which you wish to have installed upon start-up  of  the
 emulator.  If  you  add  your PC-Dragon directory to your  PATH  environment
 variable then you will not need to change into the correct directory  before
 running PC-Dragon.
 
 If  all  is  well then the title screen for the emulator will be  displayed.
 Press  a  key and the Dragon will begin its boot sequence. Once the emulator
 is  running any keys that you press will be input to the Dragon rather  than
 the  PC, but pressing F1 to F10 will access menus which control the emulator
 (so long as there are no outstanding key presses in the keyboard buffer). At
 any  time  you can press keys CTRL-ALT to activate to the control menu,  and
 CTRL-Q or CTRL-X to exit from the emulator. This will immediately return you
 to MS-DOS.
 
 The emulator will automatically locate and use any ROM files which are found
 in  your  PC-Dragon directory or CARTRIGE sub directory. However if  no  ROM
 files can be found or your command line options cannot be fulfilled then the
 emulator will report an error message and fail to start.
 
 There  are  many  command line options which may be used with  PC-Dragon  to
 configure the behaviour of the emulator. Any that you use regularly  may  be
 placed in the file PCDRAGON.CFG in the same directory as DRAGON.EXE and will
 then  be  used  as  defaults upon start-up of the emulator.  You  can  still
 override the new defaults by typing appropriate options on the command  line
 when you start the emulator or by using the on-screen menus.
 
 
 
 2.2   Dialogue Boxes
       
 
 
 2.2.1 General Functionality
       
 PC-Dragon  features a number of dialogue boxes which are used  to  configure
 and  manage the emulator. Each appears with yellow text against a red window
 and  generally operates in a consistent manner. All boxes accept  CTRL-Q  or
 CTRL-X to quit the emulator immediately, and ESC to dismiss the dialogue box
 without making a selection.
 
 RETURN, SPACE, END and F1 to F10 may also be used to dismiss dialogue  boxes
 if  these  keys  are available. However, at other times RETURN  will  accept
 changes, F1 to F10 cannot be used from the F7 menu, END cannot be used  from
 input boxes, and SPACE or RETURN are used to access the next page when there
 is more than one page of information.
 
 
 
 2.2.2 Menus And Option Menus
       
 To  select items from the menus and option menus simply press the number key
 as listed against the item that you require.
 
 For  the  file menu (F3) you can also use `L' to load snapshots and  `S'  to
 save  snapshots. For the function key menu (F7) press either F1 to F10,  `1'
 to  `9' (same as F1 to F9), `0' (same as F10), `#' (for F6) or `A' to `Z' to
 select which key you wish to re-configure. Do not hold down the ALT key when
 you do this.
 
 
 
 2.2.3 Input Boxes
       
 Input  boxes  appear when the emulator requires you to enter a text  string.
 For  example, to instruct the emulator which filename to use for  loading  a
 snapshot, or to assign a new string to a programmable function key. When the
 input box appears the current value will be highlighted in the box, enabling
 you  to  accept  this as the new value by pressing RETURN or replace  it  by
 simply overtyping it. You can also press END (or UP/DOWN/RIGHT) to append to
 the old value or BACKSPACE to remove characters from it. At any time you can
 press HOME to delete all of the input, RETURN to accept the input, or ESC to
 abandon the operation.
 
 All  input  boxes  are  intended to input only one  string  at  a  time  and
 therefore  translate SPACE characters to underscores. This is also essential
 for  the input of function key strings, which translate underscores back  to
 spaces at the time that they are used.
 
 
 
 2.2.4 Numeric Input Boxes
       
 Numeric  input boxes behave in the same way as textual input boxes but  have
 additional features useful for the input of numeric values.
 
 By  default  numeric  input  boxes require that  new  values  are  given  in
 hexadecimal. But you can type a decimal value by preceding the value with  a
 `#'  character  or an octal value by preceding the value with  `o'  or  `O'.
 Hexadecimal numbers may be qualified explicitly by typing `$'.
 
 You  can also type the names of 16-bit registers `PC', `X', `Y', `U' or  `S'
 into  any  numeric  input  box  to represent the  current  values  of  these
 registers.
 
 
 
 2.3   Filename Entry
       
 A  number of emulator functions prompt for a filename to be entered. In  all
 cases you can type the full drive and path name to your file. Or if you give
 just  the  filename  and no directory then the emulator  will  look  in  the
 current  directory  (plus  any  other  default  sub  directories).  Filename
 extensions  are optional - the emulator will append a default  extension  if
 you do not give one. Note, however, that to specify the name of a file which
 does not have an extension you should terminate the name with a period and a
 null extension. This prevents the emulator from adding the default extension
 to the name that you give.
 
 When opening files for output the emulator will not overwrite existing files
 without confirmation.
 
 The  following are the default extensions and optional sub directories  used
 by PC-Dragon:
       
          File Type        Default Extension          Sub Directory

      
          CARTRIDGE               DGN                   CARTRIGE
      
           SNAPSHOT      PAK or D32/D64/D96/CCO         SNAPSHOT
      
                                                        CASSETTE
           CASSETTE               CAS                CASSETTE\GAMES
                                                    CASSETTE\ARCHIVE
      
          SCREENSHOT      Derived from current              -
                             display mode.
      
         SOURCE FILE              A09                       -
      
        MOTOROLA FILE             S19                       -
 
 
 2.4   Emulation Of Hardware And Peripherals
       
 
 
 2.4.1 Keyboard
       
 There  are  two modes of keyboard emulation available with PC-Dragon.  These
 are  `Real  Mode' and `PC Mode'. `PC Mode' is the default. It is  also  used
 internally by the emulator when dialogue boxes are displayed.
 
 In  `PC  Mode'  keyboard input is passed from the emulator to  the  emulated
 machine  by  breakpointing the installed operating system ROM and  returning
 the  character code equivalent to the PC key pressed. This method works well
 for  most BASIC software and some machine code software, and also allows the
 PC to buffer input before it is required by the Dragon. This facilitates the
 provision of the repeat buffer and the programmable function keys.
 
 However, there are some programs, particularly games software, which  access
 the keyboard at the hardware level rather than through the operating system.
 For these programs the emulator provides the `Real Mode' keyboard emulation.
 In `Real Mode' PC keys are directly equated with keys on the Dragon keyboard
 -  you  will  therefore notice that some key combinations produce unexpected
 results  on  the  screen  since  the PC and Dragon  keyboards  are  labelled
 differently.
 
 You  can switch between keyboard modes either from the general options  menu
 (F4,  1) or by typing /K on the command line when you start PC-Dragon. If  a
 program  requests keyboard data at the hardware level and you  do  not  have
 `Real  Mode' selected then the emulator will still attempt to provide  `Real
 Mode'   information  to  the  program,  however  this  pseudo  `Real   Mode'
 information  is  less compatible than true `Real Mode'.  Therefore  you  may
 still  experience problems, particularly when using programs  which  require
 keys to be pressed continually.
 
 The following PC keys are used to emulate special Dragon keys:
 
    ESC or END        BREAK key.
    HOME              CLEAR key.
    PG UP             Pause (SHIFT + @ key).
    PG DN             Continue (ENTER key).
    INS, DEL          `I' and `D' keys (as used by EDIT).
    CURSOR KEYS       Dragon cursor keys.
    CAPS LOCK         Dragon caps lock (SHIFT + 0 key).
    
 The following keys apply only to `PC Mode':
    
    SHIFT + F1 to F4  SHIFT + Dragon cursor keys.
    SHIFT + TAB       ESC key (as used by EDIT).
    
 The following keys apply only to `Real Mode':
    
    ALT + CURSOR KEYS SHIFT + Dragon cursor keys.
    ALT + ESC         ESC key (as used by EDIT).
    `[' and `]'       Brackets `(' and `)'.
 
 
 There  are also additional facilities which are available only in `PC Mode'.
 These are:
 
    Freeze Mode       Engage  SCROLL  LOCK to inhibit changes  to  the  video
                       mode.
                       
    Repeat Buffer     At  any  prompt press CTRL-RETURN to repeat  every  key
                       typed  between  the  two most recent  presses  of  the
                       RETURN key.
                       
    Function Keys     The  keys  F6  and ALT-F1 to F10 can be  programmed  to
                       perform  any  sequences of key presses.  Press  F7  to
                       change the current assignments.
                       
    BASIC Keywords    The  keys  ALT-A  to  Z  can be programmed  to  perform
                       sequences of key presses in the same way as above. The
                       default  assignments for ALT-A to Z keys are shortcuts
                       for  BASIC  keywords. For example  `GOTO'  for  ALT-G,
                       `NEXT' for ALT-N and `RUN <RETURN>` for ALT-R.
                       
 Please  note  that  these features are implemented at the  lowest  level  of
 keyboard  handling  performed by the emulator - all keys  can  be  simulated
 whether they represent printable characters passed to the Dragon or function
 keys handled by the emulator.
 
 
 
 2.4.2 Video
       
 The  emulator  uses the PC 40 column text mode to emulate  the  Dragon  text
 mode, with IBM approximations to Dragon graphics blocks used to simulate low
 resolution  graphics.  Graphics  modes are  emulated  using  EGA  16  colour
 graphics, with all 56 of the Dragon graphics modes fully implemented.  A  2-
 bit  encoding  scheme  is  used for all modes, with separately  configurable
 colours  for the bit pairs 00, 01 (LHS), 01 (RHS), 10 (LHS), 10  (RHS),  and
 11.
 
 Semi-graphics  modes are not supported and will merely switch  the  emulator
 into a 4 colour graphics mode of similar resolution.
 
 The  emulator  supports  optional artifacting in black  and  white  graphics
 modes.  This  may  be enabled either by using the /AR and /AB  command  line
 options  or  by using the display options menu. The emulator then  immitates
 the red/blue blur exhibited by NTSC televisions. This facility is useful for
 Dragon  emulation as well as CoCo emulation since many Dragon programs  have
 been  imported  from  the  USA where the effect  is  sometimes  used  to  an
 advantage. Examples of games which are much improved by enabling artifacting
 are Mr Dig, Zaxxon, The Vortex Factor and Shenanigans.
 
 Software  which  uses  fast  mode switching techniques  to  achieve  special
 effects  (such as parts of Rommels Revenge, Space Wrek and Zaxxon) will  not
 be displayed very smoothly by the emulator. This is because PC-Dragon cannot
 refresh the graphic screen fast enough. For such games engage SCROLL LOCK to
 defeat the effect. This fixes the display into a single video mode.
 
 
 
 2.4.3 Cassette Port
       
 The  cassette port is emulated by intercepting operating system requests for
 reading  and  writing to cassette and redirecting these to  operate  on  DOS
 files.  These files thus contain images of the data which would be contained
 on a cassette and are given the extension CAS.
 
 To  use cassette files simply type the Dragon commands exactly as you  would
 from  a  real machine (eg. `CSAVE', `OPEN', `CLOADM'). A dialogue  box  will
 then  appear  prompting you to enter the name of the cassette file  to  use.
 After  you  have  entered a valid name the cassette will  remain  accessible
 until the end is reached, until the Dragon attempts to open the stream in  a
 different  I/O mode, or until the cassette port is reset by pressing  F3,  1
 (this is useful if you encounter an IO ERROR?).
 
 Filename  prompting may also be disabled using the general options  menu  or
 the  /NN  command line option. The default name will then be used unless  an
 error is encountered.
 
 The  emulator  will optionally use sub directories CASSETTE,  CASSETTE\GAMES
 and  CASSETTE\ARCHIVE  below  your PC-Dragon directory.  If  the  GAMES  and
 ARCHIVE  sub  directories  are used then the files  that  they  contain  are
 treated as read-only.
 
 Cassette  port emulation is implemented using special I/O opcodes which  are
 installed into the ROM image(s) upon start-up of the emulator. This  enables
 the  breakpoints to remain active even if the Dragon 64 is switched into map
 mode 1 and the alternative ROM image is used.
 
 Similar  I/O  opcodes are also used for the implementation of  joystick  and
 keyboard  breakpoints. All of these may be disabled by using the /NB  option
 upon  start-up.  This gives `pure' emulation of the base machine  but  makes
 cassette facilities unavailable.
 
 
 
 2.4.4 Printer Port
       
 A  printer  may  be connected to a communications port of the  PC  and  used
 directly  from  within PC-Dragon. Either parallel or  serial  ports  may  be
 selected for output irrespective of the machine being emulated. The required
 conversion of data is performed automatically by the emulator.
 
 There  are  a number of printer options, which can be selected using  either
 the printer menu (F4, 3) or the command line options.
 
 To configure the port used for printer output specify /LPT1, /LPT2, /COM1 or
 /COM2  when  you  start  PC-Dragon.  Alternatively  printer  output  may  be
 redirected  to the file PRINTER.OUT by specifying /F or /FILE instead  of  a
 port  name.  By  default port LPT1 is used if it is present, otherwise  COM1
 will  be  used or printing to a file will be enabled. For serial  ports  the
 baud  rate  may also be specified as /B1200, /B2400, /B4800 or  /B9600  (the
 default is 2400bps). In all cases the data is transmitted as 8 bits  with  1
 stop bit and no parity.
 
 Two  modes  of  support for character output are available. In  the  default
 `basic'  mode characters are simply transmitted to the port on request  from
 the  Dragon  (provided that the printer is ready). In  `advanced'  mode  (/P
 option)  the  first character sent to a printer causes the configuration  or
 initialisation  sequence  to be issued to the printer.  Following  this  the
 emulator  will  pause for 5 seconds for the printer to  return  on-line  and
 subsequently (for parallel printers) the emulator will poll the  printer  to
 enquire  whether it is ready to receive characters before sending  data.  If
 the  printer is not ready then PC-Dragon will wait for up to 20  seconds  if
 necessary.
 
 For  printers which require both <CR> and <LF> codes as line terminators the
 emulator  may  be  instructed to automatically  translate  <CR>  codes  into
 <CR><LF>.  To do this specify /CRLF on the command line or use  the  printer
 menu.  This  feature  is  useful for text output only  and  is  disabled  by
 default.
 
 Note  that  because Dragon software often outputs garbage to printers  as  a
 side effect of generating sound, it is not recommended that advanced printer
 spooling  be  enabled  unless  printing facilities  are  actually  required.
 Moreover,  it is usually desirable to turn off any connected printer  whilst
 running  programs which do not use the printer. Networked users may wish  to
 disable printer support completely by giving the /NP option.
 
 For Tandy CoCo emulation the time which elapses between each bit sent to the
 serial port must be no greater than 10 seconds in order for the bits  to  be
 assembled  into  parallel  data. If more than 10 seconds  elapses  then  the
 current byte is assumed lost and is discarded.
 
 
 
 2.4.5 Joystick Port
       
 PC-Dragon  performs  emulation  of the Dragon  joysticks  using  either  the
 keyboard,  mouse  or PC joystick. By default a Microsoft  or  Mouse  Systems
 compatible  mouse is used, but the joystick menu (F4, 4) or /JOY option  may
 be  used  to  select the PC joystick (note that this causes a  reduction  in
 performance).  Swirl  the joystick at the start of  play  to  configure  the
 available range.
 
 You  can also choose either analogue or digital emulation. Analogue  is  the
 default  mode,  with  /G used to choose digital emulation.  If  `Real  Mode'
 keyboard emulation is selected then the keyboard may additionally be used to
 simulate  the  joysticks. The cursor or keypad arrow  keys  perform  digital
 movement, with keypad `5' providing the fire buttons. Keypad `1' and `3' may
 be used for left and right fire buttons separately.
 
 When  software  reads  the joystick positions directly  through  the  Dragon
 hardware  a  sampling rate is used by the emulator to reduce the  number  of
 unnecessary  updates  that it performs. By default  28  hardware  reads  are
 accepted  before  the stick positions are updated. To change  this  use  the
 joystick menu or /Rr to change the value (r must be in the range 0 to 255).
 
 
 
 2.4.6 Cartridge Port
       
 Machine code cassette files may be converted to the DGN format and used with
 the emulator as cartridge images. Use the Dragon Convert utility to do this.
 Cartridge  files may then be installed prior to start-up of the emulator  by
 typing  their name on the command line. They can also be installed later  by
 using the F3 menu.
 
 Cartridges  which  are  loaded from the command line  or  PCDRAGON.CFG  file
 should automatically execute if they are designed to do so. However, the use
 of  a  bootup snapshot (these are introduced in section 2.7.4) will  prevent
 the  operating system from recognising bootable cartridges and therefore  if
 necessary  you  can  type /SB to prevent the emulator  from  loading  bootup
 snapshots.
 
 The  ROM_STUB.DGN  file can be used in conjunction with  the  MS-DOS  `COPY'
 command  to make cartridge files of any cartridges that you have transferred
 to  your  PC  as  a  raw  image (eg. by uploading the  data  from  an  EPROM
 programmer).  See section 3.6 for further information on using  this  header
 file.
 
 Cartridges can be copied to cassette and transferred to PC format by using a
 sound  card  and Dragon Convert (see section 3.2). In most cases you  should
 save  either  4K  or 8K of data starting at address $C000. For  example,  to
 capture the Alldream cartridge use:
 
                   CSAVEM "ALLDREAM", &HC000, &HDFFF, &HC000
                                       
 Cartridges  which  automatically execute may be captured using  a  technique
 which is described in the documentation for CoCo2.
 
 
 
 2.5   Emulator Options And Menus
       
 
 
 2.5.1 Help Screen
       
 Press  F1  to  access the help screen. Then press SPACE or  RETURN  to  page
 through  a  summary of the available special keys. Press ESC to dismiss  the
 help screen.
 
 
 
 2.5.2 Text Viewer Menu
       
 Press F2 to access the text viewer menu. Using this menu you can invoke  the
 built-in  text viewer to display this manual or the contents  of  local  sub
 directories.
 
 
 
 2.5.3 File Management Menu
       
 Press  F3  to perform file management. You can then press `1' to  reset  the
 cassette port (useful if you encounter an IO ERROR?) or `2' to `7'  to  load
 or save various types of files.
 
 Press  `2'  or  `L' to load a snapshot, or `3' or `S' to save.  See  section
 2.7.3 for more information about snapshot files.
 
 Pressing  `4'  or  `5'  allows you to load or save  screenshots.  These  are
 unformatted files containing the contents of the currently displayed  Dragon
 screen. The default extension given to the save filename will depend on  the
 current  video  mode. It will be DTX for text mode or D## in graphics  mode,
 where ## is a number `00' to `15' representing the current resolution.
 
 The  final  two  features  on the file management menu  allow  you  to  load
 programs  in cartridge (DGN) or Motorola S-record (S19) format into  memory.
 These file types do not automatically execute upon loading.
 
 
 
 2.5.4 Options Menu
       
 Press  F4 to access the options menu. From here you can select further menus
 to change the current PC-Dragon configuration.
 
 Options accessible from these menus may also be changed by using the command
 line  when  you  start  the  emulator, using PC-Dragon  programmer  services
 (except  for options relating to snapshots), or chosen as default by placing
 the  command  line  text in file PCDRAGON.CFG. A summary  of  the  available
 command  line equivalents may be obtained by typing `DRAGON /?'  or  `DRAGON
 /H'. You can also use the UNIX style `-' rather than `/' to specify options.
 Comments  may  be  included in the configuration file by  prefixing  comment
 lines with the `#' character.
 
 Press  `1'  to  configure the keyboard mode, enable or disable the  cassette
 filename prompt, instruct the emulator to ignore or pause in the event  that
 it  encounters illegal opcodes, change the level of swapping,  or  configure
 the IRQ rate.
 
 Press  `2' to turn lower case text on or off, turn the PC cursor on or  off,
 or change the current artifacting mode.
 
 Press `3' to change the printer port and serial baud rate, enable or disable
 <CR> to <CR><LF> translation, or change the printer interfacing mode.
 
 Press  `4'  to configure the joystick emulation device, type,  and  rate  of
 update for hardware access.
 
 Press `5' to select the format used for loading and saving snapshots, enable
 or  disable  compression of saved snapshot data, change the save length  for
 snapshots,  and  to  allow or inhibit the loading of emulator  options,  the
 debugger state, and PC-Dragon `extensions'.
 
 Press `6' to change the emulator colours. You should then choose either text
 mode  colours,  monochrome  graphics colours,  or  4  colour  graphics  mode
 colours.  Following this select the palette (as determined by  the  `SCREEN'
 command)  and  choose  foreground/background  or  pixels/border  options  as
 required. If you wish to change pixel colours a menu will appear from  which
 you  should select which colour number you wish to change the appearance of.
 Note  that whether you are changing monochrome or 4 colour mode colours  the
 pixel  colours are configured based on a 2-bit encoding scheme (see  section
 2.4.2).
 
 Once the item that you wish to change has been selected a window will appear
 which shows the available colours. The current colour is indicated using `*'
 symbols. Select a new colour by pressing `1' to `9' or `A' to `F', or  press
 ESC, RETURN or SPACE to leave the colour unchanged.
 
 
 
 2.5.5 Video Mode Menu
       
 Press  F5  to change the current Dragon video mode. You can then  alter  the
 number  of  available  colours, the palette number  in  use,  the  width  of
 graphics  mode  pixels,  the number of bytes of RAM used  for  video  memory
 (together  with  the pixel width this determines the resolution  of  graphic
 modes), and the base address of video memory.
 
 A number of short-cut keys are also available. You can switch immediately to
 PMODEs 1 to 4 by pressing CTRL-F1 to F4, and to text mode by pressing  CTRL-
 F8.  To toggle the palette, number of colours, and pixel width, press  CTRL-
 F5, CTRL-F6 and CTRL-F7 respectively.
 
 
 
 2.5.6 Function Key Configuration
       
 Press  F7  to change the assignment of `PC Mode' function keys.  Change  the
 text string simply by pressing the key that you wish to change (without ALT)
 and  then enter the new text string. To change the F6 key press `#', but  if
 you do so then you will need to press `6' if you later wish to reassign ALT-
 F6.
 
 See section 2.7.6 for more information on function key assignments.
 
 
 
 2.5.7 Control Menu
       
 Press F8 to access the control menu. You can also access the control menu by
 pressing  the  key combination CTRL-ALT. Note, however, that  CTRL-ALT  will
 work at any time whereas F8 will only work when the keyboard buffer is empty
 (this  only  applies  when  `PC Mode' keyboard emulation  is  selected,  but
 applies to all emulator control keys).
 
 From the control menu you can perform warm or cold restarts (equivalent to a
 real machines RESET button and OFF/ON switch respectively). You can also run
 an MS-DOS shell or switch to the debugger.
 
 Accessing the control menu discards any key presses in the keyboard buffer.
 
 
 
 2.5.8 Assembler Menu
       
 The assembler menu is accessed by pressing F9. This menu provides facilities
 which  integrate the emulator to an assembler. It is discussed in detail  in
 section 2.6.1.
 
 Alternatively,  pressing  CTRL-F9 jumps directly  to  the  editor  and  then
 returns to the assembler menu when editing is complete.
 
 
 
 2.5.9 Information And Configuration Screen
       
 Press  CTRL-F10  to  display the information and configuration  screen.  The
 screen  displays  a  summary  of  the current  PC-Dragon  configuration  and
 additional transient information such as a description of the current  video
 mode.
 
 The  information screen also shows the performance of the emulator  relative
 to  a  real  Dragon. This calculation is based on the time taken to  execute
 instructions equivalent to two seconds on a real machine (i.e. normally this
 is  100  counts  of  the TIMER function). The speed is  only  measured  when
 required,  and is not updated unless the emulator was executing continuously
 during the two emulated seconds prior to CTRL-F10 being pressed.
 
 Press ESC to return to the emulator.
 
 
 
 2.6   Program Development Tools
       
 
 
 2.6.1 Integration Of The Emulator With An Assembler
       
 PC-Dragon  includes  integrated support for the freeware Motorola  assembler
 AS9.EXE. To use the assembler activate the assembler menu by pressing F9 and
 then press `1' to edit your source file. Pressing  CTRL-F9 also has the same
 effect.  PC-Dragon then starts your text editor and returns to the assembler
 menu when you exit. You can now press `2' to call the assembler.
 
 If  the  assembly  completes successfully then PC-Dragon  will  display  the
 message  `Assembled with no errors!' and load the program image into memory.
 If  unsuccessful then a TextView window will open to allow you to review the
 assembler output. To edit the source again press `1' as above.
 
 At a later time you can return to the assembler menu and press `3' to reload
 the  program  image (this also exits the menu) or `4' to view the  assembler
 output again.
 
 To  change  the  6809  source filename used press  `5'  and  enter  the  new
 filename.  By default `SOURCE' is used and the extension `A09' is  appended.
 The source filename may also be specified on the command line when you start
 PC-Dragon by preceding it with an `@' character.
 
 To  configure the paths for the assembler and your favourite editor use  the
 /IA  and  /IE command line options. These should followed by the path  name.
 Eg.
 
                DRAGON  /IAC:\UTILS\AS9  /IEB.EXE  @MY6809.ASM
                                       
 Please be warned that AS9.EXE seems to implement memory allocation in a  way
 which  is  incompatible  with PC-Dragon. You may  experience  crashes  after
 calling the assembler, particularly if you try to run an MS-DOS shell.
 
 
 
 2.6.2 Built-In Debugger
       
 PC-Dragon  includes  a  powerful  built-in debugger  and  disassembler.  The
 debugger  tracks  recently executed instructions,  allows  modifications  to
 registers, flags and memory, and supports a wide range of break conditions.
 
 To  switch to the debugger press F10 or select the debugger from the control
 menu. The debugging screen will then be displayed.
 
 The  screen contains three windows. On the left hand side is a window  which
 may display the current Dragon text screen, help pages for the debugger,  or
 a  memory  dump  (beware that selecting the memory dump display  slows  down
 single step operation).
 
 At  the  bottom  of  the  screen  is a small  window  in  which  status  and
 informational messages appear.
 
 The right hand half of the screen is used for the main debugger window. This
 contains a disassembly section, a section showing the contents at the top of
 the  user  and system stacks, a section displaying the current register  and
 flag values, and a section displaying the current global breakpoints.
 
 The  disassembly  section  of the main window shows  the  four  most  recent
 instructions  executed (if known), the current instruction  (highlighted  in
 blue),  and  the  next  four  instructions to  be  executed  (assuming  that
 execution proceeds linearly).
 
 The  disassembly section also contains a cursor denoted by `>` and `<`.  The
 cursor  is used to mark addresses on a temporary basis and may be  moved  up
 and  down  the display using the cursor keys, or returned to the address  of
 the  program  counter by pressing HOME. If you move the  cursor  beyond  the
 bottom  of  the  display  then  the disassembly  will  scroll  to  the  next
 instruction.
 
 The functions of the debugger are accessed using the following keys:
 
      1       Set  breakpoint  1 address. Keys `2' to `6' similarly  set  the
              addresses for breakpoints 2 to 6. These breakpoints are global,
              remaining  active  in  addition to any other  break  conditions
              which are selected.
              
      A       Display  the  effective  address associated  with  the  current
              instruction.
              
      B       Set temporary a breakpoint and continue execution.
              
      D       Switch to disassembler. Enter the required start address at the
              prompt.  Then  SPACE scrolls the disassembly by  a  full  page,
              ENTER  and  DOWN keys scroll the display by a single line,  and
              `D' allows a new address to be specified.
              
      E       Quick edit memory - does not prompt for a new address.
              
      F       Toggle CPU flags. Press keys appropriate to the flags that  you
              wish to toggle.
              
      G       Continue execution until a global breakpoint is reached.
              
      H       Display main help page. Press `H' again for the secondary  help
              page.
              
      I       Fill  memory with a constant value. Enter the required boundary
              addresses  and  the  fill value. Memory  will  then  be  filled
              inclusive of the addresses given.
              
      M       Dump  or edit memory. Enter the required address at the prompt.
              Then  change the values as required, scroll up and  down  using
              the cursor keys, or press TAB to switch between the hexadecimal
              and ASCII sections of the display.
              
      N       This key causes the conditional jump at the current address  to
              be evaluated. Program execution then continues until evaluation
              of  the  condition  gives a different result  and  a  different
              execution path is taken.
              
      O       Continue  execution until a specific opcode is  reached.  Enter
              the required opcode at the prompt.
              
      Q       Continue execution until an RTS instruction is reached.
              
      R       Change  register values. Press a key to indicate which register
              you  wish to change and then enter the new value. If you assign
              a  value larger than 255 to the A or B registers then the value
              will be assigned to D.
              
      S       Step to the next instruction.
              
      T       Display the current Dragon text screen in the left hand  window
              (this use of the window is selected by default).
              
      V       Continue  execution  until  a  register  has  been  assigned  a
              specific value. Press a key to select which register is  to  be
              monitored  and  then enter the value on which execution  should
              halt.  You can also enter the current value of the register  to
              instead break on a change in the value of that register.
              
      X       Continue execution with a new program counter value. Enter  the
              required new program counter value at the prompt.
              
    SPACE     Step  over  to the next instruction. This command is equivalent
              to  the  `S' command except when the current instruction  is  a
              JSR,  BSR  or  LBSR  instruction. After stepping  over  a  jump
              instruction   the   disassembly  continues   to   display   the
              instructions  stepped  over rather  than  those  most  recently
              executed.
              
    RETURN    Set  temporary  breakpoint at the current  cursor  address  and
              continue execution.
              
     TAB      Set or remove a global breakpoint at the current cursor address
              (LEFT and RIGHT cursor keys also have the same function).
              
 To  quit  from the debugger press either ESC or END. Once you have quit  all
 execution tracing and break conditions are suspended. This gives the fastest
 possible  execution speed. If you dismiss the debugger screen with  commands
 such  as  `B',  `G' or `X' then the debugger will still be  active  and  the
 performance of the emulator will be reduced.
 
 
 
 2.6.3 Emulator Services
       
 PC-Dragon  provides  a  range of services to allow the  emulated  Dragon  to
 access the emulator environment and configuration options.
 
 The  services  are accessed by the use of special write-only memory  in  the
 region $FFEC to $FFEF and may be used from both BASIC and machine code. Upon
 start-up  of  the  emulator the services are disabled in order  to  maintain
 software compatibility.
 
 To  enable the services simply write $50 to address $FFEE and $43 to address
 $FFEF.  They  may then accessed by reading from address $FFEE or  $FFEF.  If
 $FFEE is read then the 6809 registers A, B, X, Y and U are used to pass  any
 required parameters to the services and to receive the results. If $FFEF  is
 read  then  memory is used instead. Memory locations $FFEC and $FFED  should
 point  to  the  address  of the parameters, which must  be  formatted  as  a
 register dump in the order A, B, X, Y and U. On start-up of the emulator the
 contents of $FFEC and $FFED are initialised to point at $FFE0; enabling  the
 services also makes $FFE0 to $FFEB available as RAM.
 
 The  services available in this version of PC-Dragon are listed in  Appendix
 A.  In  all  cases  the B register is used to indicate the required  service
 number.  All  registers  not  explicitly specified  in  the  table  are  not
 affected,  and  all  services return 0 upon success, 255  if  the  requested
 service  is not supported, or an error code as specified. Appendix  B  lists
 the colour values used by the colour configuration services.
 
 An example code fragment to initially detect PC-Dragon is given below:
 
     LDD #$5043   ; Enable PC services.
     STD $FFEE
     LDX #0       ; Set X <> signature.
     CLRB         ; Service 0: installation check.
     TST $FFEE    ; Call emulator service.
     CMPX #$5043  ; Check for PC-Dragon signature.
     BNE NOTPCD
 
 The following will change the default text screen colours to BLUE on BUFF:
 
     LDD #$5043   ; Enable PC services.
     STD $FFEE
     LDD #5       ; Service 5: set text colours.
     LDX #$1706   ; Setup new colours.
     TST $FFEE    ; Call emulator service.
 
 To turn on the PC cursor from BASIC:
 
     POKE &HFFEE,ASC("P")           `Enable PC services.
     POKE &HFFEF,ASC("C")
     POKE &HFFE1,2                  `Service 2: cursor control.
     POKE &HFFE0,1                  `New state is solid.
     I=PEEK(&HFFEF)                 `Call service.
 
 Finally, the following is a short program which will allow the mouse to draw
 on  a PMODE3 graphics screen. The normal drawing colour will be yellow. Hold
 down the left mouse button for blue, the right mouse button for red, or both
 to erase.
 
     10 PMODE3:SCREEN1,0:PCLS
     20 POKE &HFFEE,ASC("P")          `Enable PC services.
     30 POKE &HFFEF,ASC("C")
     40 POKE &HFFE1,8                 `Service 8: get mouse status
     50 IF PEEK(&HFFEF) THEN STOP     `Call service, check return.
     60 COLOR (PEEK(&HFFE0)+2) AND 7  `Set colour from button info.
     70 LINE-(PEEK(65507),PEEK(65509)),PSET   `Draw line to cursor.
     80 GOTO 50
 
 
 2.7   Additional Information
       
 
 
 2.7.1 Video Refresh Interrupt
       
 The  video refresh IRQ is emulated by PC-Dragon, and occurs relative to  the
 emulated machine speed (every 17,800 emulated clock cycles). However,  since
 the emulator does not run at real speed, the frequency of the interrupt does
 not  match  the 50Hz signal of the real machine. On a 486DX-33 the frequency
 is approximately 20Hz.
 
 To  mask this deficiency the interrupt rate may be artificially increased if
 required. Simply use the general options menu or the /Q option to alter  the
 number of cycles between interrupts. This allows some programs which use the
 IRQ  interrupt for timing purposes to run faster (eg. Chuckie Egg), as  well
 as reducing the pauses during sound effects in some software.
 
 PC-Dragon does not emulate the horizontal retrace signal.
 
 
 
 2.7.2 Illegal And Undocumented Instructions
       
 PC-Dragon  includes  emulation of the undocumented RESET  opcode,  and  also
 treats  undocumented `illegal' register transfers and exchanges in the  same
 way as a real 6809.
 
 In  order  to  maximise  speed no action is taken for illegal  indexed  mode
 postbytes.  Eg.  STA (,U+) does not officially exist but  will  be  executed
 correctly by PC-Dragon due to the symmetry of the instruction set.
 
 When  other  unknown  opcodes are encountered the emulator  will  pause  and
 display  a window describing the problem. The message invites you to  choose
 an  action  for handling the opcode. You may ignore the opcode,  ignore  all
 future  illegal opcodes (this choice may also be selected as  default  using
 the  general options menu or /II command line option), or you can switch  to
 the  control  menu. The debugger may be accessed from the  control  menu  if
 required.
 
 
 
 2.7.3 Snapshots
       
 Snapshots  are  frozen images of the current state of the  emulated  machine
 together with the current emulator configuration options. They may be  saved
 at  any  time  and  loaded back later to restore the emulator  and  emulated
 machine to the exact same state.
 
 By default the emulator will use a snapshot format which is fully compatible
 with  the  CoCo2  emulator, although you must use the  snapshot  options  to
 configure which version of CoCo2 you have (the default is V1.4).
 
 There  are  also  snapshot  options  to  disable  the  loading  of  optional
 information  from snapshots. The saved length of snapshots  may  be  changed
 (but  not the start address), and Run Length Encoded compression may be used
 when  snapshots  are saved. Compression can significantly  reduce  the  disk
 space  required for storing snapshots but you should be aware  that  if  you
 choose  to use compression then saved snapshots will no longer be compatible
 with  CoCo2.  The PC-Dragon implementation of RLE compression  automatically
 optimises  the  substitution  codes for each snapshot  but  the  performance
 achieved  is  still  much  less  than  that  available  using  more  complex
 techniques.
 
 All  snapshots saved by PC-Dragon also contain additional information  which
 is  not  used  by  CoCo2. These `extensions' contain a  description  of  the
 current debugger state (current breakpoints, last edit address, active break
 conditions, etc.), additional machine state information, and additional user
 options. However, the `extensions' are incorporated into the snapshot format
 in a way which does not affect compatibility with CoCo2.
 
 When a snapshot is loaded by PC-Dragon it will automatically detect and  use
 the `extensions' if they are present. Note however that if you manually edit
 a  snapshot or load one into CoCo2 are re-save it then the `extensions' will
 be  destroyed. This will rarely cause problems but it is possible to  reduce
 the  usefulness of a snapshot in this way. For example, because the original
 format  does not contain all of necessary PIA data, many snapshots saved  by
 CoCo2  cannot  be  loaded  from the command line without  finding  that  the
 keyboard  is  unusable  in `Real Mode' (using a BOOTSNAP  file  can  usually
 correct this problem).
 
 By  default PC-Dragon uses the PAK extension when saving a snapshot. PAK  is
 also  used when loading but in addition to this the emulator will  look  for
 snapshots  with  extensions  D32, D64, D96 or  CCO  as  appropriate  to  the
 architecture being emulated.
 
 The  extension  D96 is used to identify snapshots which are compatible  with
 both  Dragon  32  emulation  and Dragon 64 emulation.  An  option  from  the
 snapshot  menu can be used to specify the portability of snapshots prior  to
 using  the  snapshot  save facility. A snapshot can be  designated  as  non-
 portable, portable to any Dragon, or portable to any supported architecture.
 The  `Incorrect ROM' warning message is then inhibited when the snapshot  is
 reloaded.  Note,  however,  that this feature is  implemented  for  cosmetic
 reasons only - the emulator automatically attempts to repair snapshots which
 are  loaded  into incompatible architectures irrespective of the portability
 designation.
 
 When loading a compressed snapshot file you do not need to specify that  the
 snapshot  is  compressed  or set the correct snapshot  format  version.  The
 emulator  will automatically detect the snapshot format used and  uncompress
 the data.
 
 To  configure the snapshot options from the command line use /SV followed by
 the  version of CoCo2 that you have (`2', `3' or `4'), /SP followed  by  the
 portability  designation to be given to saved snapshots (`N', `D'  or  `A'),
 /SC  to enable or disable compression, /SL followed by a number in the range
 1 to 65280 indicating the snapshot save length, /SO to inhibit the retrieval
 of   emulator  options  when  snapshots  are  loaded,  /SD  to  inhibit  the
 restoration   of   the  debugger  state,  and  /SX  to   inhibit   PC-Dragon
 `extensions'.
 
 If  you  have  the  NDUG release of CoCo2 V1.2 then you should  select  V1.2
 format snapshots. For the Internet releases of CoCo2 V1.2 and CoCo2 V1.3 you
 should select V1.3 format, and for CoCo2 V1.4 select V1.4 format.
 
 
 
 2.7.4 Bootup Snapshots
       
 At  start-up  PC-Dragon  attempts to speed up initialisation  by  loading  a
 snapshot which has been prepared with an image of a fully booted up machine.
 If such a snapshot if found then the snapshot is executed immediately rather
 than  you having to wait whilst the emulated machine performs a cold  reboot
 and self-test.
 
 Bootup  snapshots  must  be in compressed format and  named  BOOTSNAP  (with
 extension D32, D64 or CCO as appropriate). They are always loaded  with  PC-
 Dragon `extensions' enabled and emulator options and debugger state ignored.
 
 Working  bootup snapshots are included with this distribution  of  PC-Dragon
 but  may  be replaced if required. If you wish to do this you should  ensure
 that  you use the emulator with `Real Mode' keyboard emulation selected when
 booting  the Dragon to prepare your snapshot. If you forget to do this  then
 the  bootup snapshot will not contain the PIA information necessary  to  use
 `Real Mode' keyboard emulation in the future.
 
 The  command  line /SB option may be used to disable the loading  of  bootup
 snapshots.
 
 
 
 2.7.5 Swapping
       
 PC-Dragon  is  able to swap memory to disk prior to functions which  require
 auxiliary  programs to be called. This makes more base memory  available  to
 these programs.
 
 With  no  swapping  PC-Dragon may use up to 310K of base  memory,  but  with
 swapping enabled PC-Dragon can reduce it's usage to 190K.
 
 The  default  swapping option causes memory to be swapped out to  disk  only
 when  you call an MS-DOS shell. The swapping level may be increased so  that
 swapping  is also enabled for calls to your editor or prior to all calls  to
 auxiliary  programs.  To change the swapping level use  either  the  general
 options menu or /IS (and a number from 0 to 3) from the command line.
 
 
 
 2.7.6 Function Key Assignments
       
 With  `PC Mode' keyboard emulation selected the keys F6, ALT-F1 to F10,  and
 ALT-A  to  Z  may be programmed to simulate other key presses. The  function
 keys  may  be  programmed with up to 64 characters each and the letter  keys
 with  up to 10 characters each. To change the assignments use the /F option,
 the emulator services, or the F7 key. The default assignments are listed  in
 Appendix C.
 
 The  new strings should normally be given in lower case. This is because the
 strings  represent  key  presses rather than formatted  input  and  will  be
 translated  to  upper case at the time that they are passed  to  the  Dragon
 operating  system. Note also that underscore should be used instead  of  the
 SPACE character since SPACE is interpreted as an option separator by MS-DOS.
 
 From the command line /F should be followed by the name of the key to change
 and the new text string. For the key identities give `#' for F6, `1' to `10'
 for  ALT-F1  to F10, and `A' to `Z' for ALT-A to Z. The text string  may  be
 delimited  by any valid character. Eg. `DRAGON /FCXcloadmX' is an acceptable
 string  assigning  the BASIC keyword `CLOADM' to ALT-C  and  using  the  `X'
 character as a delimiter.
 
 The  text  strings  may  contain control sequences in addition  to  ordinary
 characters. To specify a control character simply use the `^' notation.  Eg.
 `DRAGON /F#!^Q!' programs F6 to quit the emulator. The `^' character is also
 used  as  an  escape  character, so that `^^' represents  the  UP  key.  The
 sequence  `^@' may be used for the null character, thereby enabling extended
 ASCII codes to be simulated. For example `^@B' represents the F8 key.
 
 
 
 2.7.7 Changing Emulator Colours From The Command Line
       
 To  change the emulator colours from the command line the /O option is used.
 This should be followed by `T' for text colours, `G' for graphics colours or
 `B'  for border colours. Then `0' or `1' for the `SCREEN' value, and (except
 for  text mode) `0' or `1' for PMODE0 (monochrome) or PMODE1 (4 colour mode)
 colours.
 
 After  these  items you should give the new colour as a hexadecimal  string.
 For  text mode the required hexadecimal string is two characters. The  first
 of  these  represents  the foreground colour and the second  the  background
 colour.  These are in the range `0' to `F', using the standard PC text  mode
 colour mappings (see Appendix B).
 
 For graphics mode colours a string of six EGA colour values is required; one
 byte  for each of the 2-bit values in the scheme described in section 2.4.2.
 For border colours a single EGA colour value is required.
 
 
 
 2.7.8 Cassette Files
       
 The  CAS  file  type  used by the emulator is simply a  raw  bit  stream  of
 cassette data. Because of this it is simple to append one cassette onto  the
 end  of  another by using the MS-DOS `COPY' command (the /B switch  must  be
 given  so  that  a  binary  copy is performed). For example,  the  following
 command  will  add  the  cassette EXTRA.CAS onto the  end  of  the  cassette
 FIRST.CAS:
 
                  COPY /B   FIRST.CAS + EXTRA.CAS   FIRST.CAS
                                       
 Since  the  emulator does not need to start and stop a cassette recorder  it
 does  not  need  a  motor  delay when writing data. File  headers  are  also
 optional. You can therefore speed up PC-Dragon writes to cassette (and  save
 on  disk  space)  by  issuing the following POKEs before you  type  `CSAVE',
 `CSAVEM' or `OPEN' commands:
 
 For Dragon ROM:
 
           POKE 144,0 : POKE 145,1    `Reduce number of leader bytes.
           POKE 149,0                 `Reduce cassette motor delay.

 For Tandy CoCo ROM:
 
           POKE 146,0 : POKE 147,1    `Reduce number of leader bytes.
                                      `Cannot reduce Tandy CoCo motor delay.

 If  you are planning to use Dragon Convert to transfer files back to a  real
 Dragon  then you should save the file with sufficient leader bytes  for  the
 real Dragon to detect. For example, you could type:
 
 For Dragon ROM:
 
           POKE  144,3                `Increase number of leader bytes.

 For Tandy CoCo ROM:
 
           POKE  146,3                `Increase number of leader bytes.

 Cassette  files  containing machine code programs can be  used  with  either
 Dragon or Tandy CoCo emulation but are unlikely to execute correctly on both
 platforms  due  to the differences between the ROMs of the  machines.  BASIC
 programs,  however, can be used and executed on either of  the  machines  so
 long as they are saved in ASCII format. Eg.
 
                              CSAVE "BAS-PROG", A
                                       
 will  save a BASIC program in a cassette file which can be used with  either
 Dragon  or Tandy CoCo emulation. More disk space is required when files  are
 saved  in  this format and the time taken to load and save is  also  greatly
 increased.
 
 
 
 3     File Transfer
 
 
 
 3.1   Overview
       
 PC-Dragon  includes additional utilities to support the transfer  of  Dragon
 cassette and disk software to the PC. To transfer cassette software you will
 need  either a SoundBlaster Pro sound card or a special cable which connects
 the PC parallel port to a cassette recorder. Either method works reliably so
 long  as cassettes are of reasonable quality. To transfer disk software  you
 will  need  additional Dragon-DOS disk reading software such as Compusense's
 PC Convert.
 
 The documentation for CoCo2 also describes methods for transferring software
 using  a  serial cable (Dragon 64 and Tandy CoCo only), and for transferring
 cartridges to the PC.
 
 After transferring software to the emulator you should be aware that it  may
 not function correctly in the following cases:
 
      1)   Software  which  uses  semigraphics display  modes  or  fast  mode
           switching will not be displayed correctly.
           
      2)   Any  software that plays music or sound effects will  suffer  from
           long pauses.
           
 In any event you should expect the software to run no faster than 40% of the
 correct  speed, and even slower if your program makes use of high resolution
 graphics or your PC is below the recommended specification.
 
 The  following sections describe the included utilities. These translate  PC
 files in various formats to or from the formats used by the emulator.
 
 
 
 3.2   Dragon Convert
       
 Dragon  Convert is a multi-purpose utility to convert various file types  to
 the virtual cassette format used by PC-Dragon. It can convert sampled Dragon
 cassettes in digital audio format (WAV and VOC files), Dragon-DOS files (BIN
 and  BAS),  PC-Dragon cartridge files (DGN), QBasic (BAS)  and  pure  binary
 files.  In  can  also be used to convert files from virtual cassette  format
 into cartridge (DGN) or QBasic (BAS) format.
 
 The  filename  of  the  file to be converted should be  given  as  the  last
 argument  to Dragon Convert (`DRAGON' is otherwise used as the default).  If
 no  extension is given then the program will look for a file with  extension
 WAV, VOC, BIN, BAS, DGN or CAS.
 
 The different methods of operation of Dragon Convert are described below.  A
 summary of the available command line options may be obtained by typing `DC'
 with no arguments.
 
 
 
 3.2.1 Extracting Files From Sampled Cassettes
       
 Where the input to Dragon Convert is a WAV or VOC file the audio information
 is  scanned  for  Dragon cassette data and converted to a  virtual  cassette
 file.  The  output filename is derived from the Dragon filename rather  than
 the input filename.
 
 During conversion Dragon Convert displays a counter to show the progress  in
 converting  the files. If the cassette programs conform to the  conventional
 Dragon  cassette format then the filenames and load/execution  addresses  of
 binary  files are listed as the programs are encountered. All of  the  files
 contained in a single input file will be placed in a single output file.
 
 If  Dragon Convert detects a loading error in the WAV or VOC file  then  you
 are given the option to abort the conversion, retry a block, or proceed with
 the  conversion ignoring the error. If you choose to ignore errors then  the
 converted file is unlikely to be usable, although several programs do  exist
 which deliberately contain errors.
 
 If  you choose to retry a block then the current conversion parameters  (see
 below)  appear  so that different parameters may be entered.  Type  the  new
 values  at the prompt or press RETURN to leave a parameter unchanged. Dragon
 Convert  then  attempts  to load the block using the new  parameter  values.
 There  is, of course, no advantage to be gained by retrying a block  without
 adjusting either of the parameters.
 
 Dragon  Convert  will normally assume that the sampled file  begins  with  a
 leader, and will initially seek the leader to synchronise with the data.  In
 cases  where  a leader is not present this may cause data to be  missed.  To
 avoid this give the /L option on the command line to disable the feature.
 
 Although  Dragon  Convert is designed to work with data in the  conventional
 Dragon  cassette  format  it may also be used with  cassettes  which  use  a
 proprietary  format. For such programs specify /R on the  command  line  and
 Dragon  Convert will scan the input as a raw bit stream. This results  in  a
 file  called CASSETTE.CAS. When Dragon Convert is used with this option  the
 display  shows only the number of bytes converted and loading errors  cannot
 be reported.
 
 The following actions may be taken if you suffer from loading errors:
 
           Use  the  highest available sampling rate for your sound card.  At
           least 22KHz is required.
           
           The  amplitude  of  the  input data should  comfortably  span  the
           available range. Increase the input volume if necessary.
           
           It  is a good idea to clean up the wave form before presenting  it
           for  conversion.  Try  cutting any white space  before  the  first
           program block and omitting any noisy parts of the leaders.
           
           MS-Windows  software (Eg. Creative Wave Studio)  usually  produces
           better results than MS-DOS based software.
           
           The wavelength amplitude threshold may be specified on the command
           line using the /Wn option. For a 44KHz sample a threshold of 29 to
           31 is usually correct. For 22KHz files the value of n should be in
           the range 12 to 15.
           
           The  relative volume of the wave form may be specified  using  the
           /Sn command line option, where 0 < n < 126.
           
 You  can abort the operation of Dragon Convert in the middle of a conversion
 by pressing the CTRL key.
 
 
 
 3.2.2 Converting Other File Types
       
 Dragon  Convert can be used to add the required cassette formatting data  to
 several  file types so that they may be loaded into the emulator  using  the
 virtual cassette system. To do this simply specify the filename of the input
 file on the command line.
 
 When  used  to convert cartridge (DGN) files to cassette format  the  output
 filename is taken from the header of the cartridge file. In all other  cases
 the output filename is derived from the input filename. Output is always  to
 the current directory.
 
 For  Dragon-DOS and cartridge files the header information held in the  file
 is  retained by the cassette file. For other binary files the cassette  file
 is given a load address of $600 and an execution address of $167.
 
 When  an  ASCII file is converted it is assumed to be a QBasic file  and  is
 converted   to   a   gapped  ASCII  BASIC  cassette  file.  Dragon   Convert
 automatically reformats the carriage returns and line feeds in the  file  to
 Dragon  format  and ensures that the line numbers have appropriate  spacing.
 You must save your QBasic files in ASCII format to use this facility.
 
 An  ASCII  input file may instead be converted to a cassette file in  binary
 format  by giving the /B option on the command line. This also inhibits  the
 reformatting of the data.
 
 
 
 3.2.3 Converting Files From Cassette Format
       
 A  secondary  use  of Dragon Convert is to convert cassette  files  back  to
 digital audio format so that they can be written to cassette and loaded into
 a  real  machine. When converting to audio format the cassette file  is  not
 examined  thereby  enabling  any  file type  or  proprietary  format  to  be
 converted.  To  use  Dragon  Convert for this  purpose  simply  specify  the
 filename of a cassette file when you start the program.
 
 By  default  a  44KHz  WAV file will result. This gives  very  high  quality
 playback  but  requires more than 8Mb of hard disk space for  a  32K  Dragon
 file.  You  can  therefore optionally specify /22 on  the  command  line  to
 request a 22KHz output file (or /11 for 11KHz).
 
 Dragon  Convert  can  also be used to convert cassette files  to  two  other
 formats. Machine code or tokenised BASIC cassette files may be converted  to
 PC-Dragon  cartridge files, and ASCII BASIC cassette files may be  converted
 to QBasic files.
 
 Specify  the  /D option to perform these conversions. If the input  file  is
 found  to  contain  errors then Dragon Convert will  exit  immediately.  Bit
 stream cassette files are also rejected.
 
 
 
 3.3   CopyCas Utility
       
 CopyCas  is  a  utility to make renamed copies of cassette  files.  It  will
 choose  an  appropriate  new DOS filename and copy  the  data  held  in  the
 cassette file renaming the first Dragon file at the same time.
 
 The syntax for CopyCas is as follows:
 
               COPYCAS  [/C]  dragon-source  dragon-destination
                                       
 The  filenames that are required are the Dragon filenames rather than  names
 of  the  equivalent  DOS files. They are not case sensitive  unless  the  /C
 option is given.
 
 CopyCas  will fail if the first block in the cassette file is not  a  header
 block, if the block is not aligned with byte boundaries in the file,  if  an
 ?IO  ERROR  is encountered in the first block, or if the Dragon  source  and
 destination filenames translate to the same DOS file.
 
 Please  note  that  both CopyCas and Dragon Convert will overwrite  existing
 files without warning.
 
 
 
 3.4   WhatIs Utility
       
 WhatIs  is  a general purpose utility which uses simple heuristic  rules  to
 recognise  and extract information from various types of file. It can  probe
 cassette, snapshot and cartridge files and describe their contents  in  some
 detail. Specify the name of the file to be examined when you run WhatIs.
 
 WhatIs  has  two  modes  of operation. By default it  will  simply  print  a
 sentence  or  two  describing the contents of the input  file.  For  a  full
 description  of the input file run WhatIs in verbose mode by giving  the  /V
 option  on  the command line. It will then decode as much of the information
 in the file as it is able to recognise.
 
 When  used  in verbose mode with a cassette file, for example,  WhatIs  will
 print  a  breakdown of the names and cassette blocks for all of  the  Dragon
 programs  in  the file. When used with a snapshot file it will describe  the
 machine state which is encapsulated in the snapshot and the emulator options
 which are required.
 
 WhatIs  also attempts to classify approximately 50 other common file  types,
 in  a  similar manner to the `FILE' command of UNIX. All decisions are based
 on the contents of the file and not the filename or extension.
 
 
 
 3.5   ReadVoc Utility
       
 ReadVoc  is  a utility which can read Dragon cassettes via the  PC  parallel
 port. It requires a special cable to be constructed but this is a simple and
 inexpensive process. The circuit diagram for the cable is included with  the
 emulator  -  to view it start PC-Dragon by typing `DRAGON DIAGRAM'.  If  you
 choose to construct the cable then you would be advised to also obtain `z80-
 302.zip'  and utilise the test and calibration programs supplied  with  this
 emulator.
 
 Once  you  have the cable connected and your cassette set up you can  sample
 cassettes  into  PC files by typing `READVOC' and the name of  the  required
 output  file. The resultant VOC file may then be converted to the  PC-Dragon
 virtual cassette format using Dragon Convert as described above.
 
 READVOC.COM  and  the  DIAGRAM files are the work and  copyright  of  Gerton
 Lunter.  To obtain a command summary for ReadVoc start the program  with  no
 command line arguments.
 
 
 
 3.6   How To Transfer Your ROM
       
 There  are  several  ways to transfer your ROM for use with  PC-Dragon.  The
 method  suggested  here  is to use the included Dragon  Convert  utility  to
 transfer  the  ROM  in  the same way as cassettes. Alternatively  you  could
 transfer  the ROM on disk, use a serial cable, or use the same ROM  file  as
 you use with the CoCo2 emulator. If you have access to Internet FTP then you
 may  be  able to download a copy of the ROM from an anonymous FTP site  (one
 such    site    is    faui43.informatik.uni-erlangen.de    as    the    file
 `/mounts/epix/public/pub/pc/msdos/emulators/dragon/6809roms.zip').
 
 The procedure for transfer via cassette and the Dragon Convert utility is as
 follows:
 
     1)  Boot up your Dragon 32, Dragon 64 or Tandy CoCo.
          
     2)  Ready  your  tape  recorder for recording  and  commit  the  ROM  to
          cassette by typing:
          
                      CSAVEM "DRAGROM", &H8000, &HBFFF, 0
                                       
         If  you  have a Tandy CoCo you may optionally use the name  TANDYROM
          rather than DRAGROM.
          
     3)  Boot  up  your  PC  and SoundBlaster Pro wave form editor  software.
          Sample  the cassette recorded in step 2 into a file. Alternatively,
          use  the  parallel cable and the ReadVoc utility.  A  large  output
          file should result.
          
     4)  Now use Dragon Convert to extract the cassette data. Type:
          
                                  DC  DRAGROM
                                       
         Please  don't  expect the conversion to work on the  first  attempt.
          You  are  likely to need to adjust the command line switches  until
          you  find  a combination which is suited to your hardware.  If  you
          still  have no success then you may wish to try repeating  step  3.
          Upon successful conversion the file DRAGROM.CAS will be created.
          
     5)  Now  use  Dragon  Convert again to convert the cassette  data  to  a
          cartridge file. Type:
          
                              DC  /D  DRAGROM.CAS
                                       
         This should produce the file DRAGROM.DGN in the current directory.
          
     6)  If  you  have  a  Dragon  64 then you may optionally  also  wish  to
          transfer  the 64K version of the Dragon ROM. This will  enable  you
          to  use  the emulator in 64K BASIC mode. The procedure to  transfer
          this  second  ROM  is much as before. Boot up your  Dragon  64  and
          switch  to  64K mode by typing `EXEC 48000'. Now commit the  second
          ROM to cassette by typing:
          
                      CSAVEM "D64ROM2", &HC000, &HFEFF, 0
                                       
         Transfer  this  file  to  your PC by using the  procedure  described
          before  in  steps 3 to 5. This time the result should be  the  file
          D64ROM2.DGN,  which should be saved in your PC-Dragon directory  or
          CARTRIGE sub directory.
          
 If  you already have your ROM image(s) in DOS format then you can create the
 required  DGN files from such raw images by using the included  header  file
 ROM_STUB.DGN.  You might, for instance, wish to transfer the ROM  from  your
 Dragon to your PC on a floppy disk if you are a disk user. To do this use  a
 program such as Compusense's PC Convert to transfer the ROM image as  a  BIN
 file.
 
 Raw  images  can be converted to DGN files using the MS-DOS `COPY'  command.
 Type:
 
               COPY  /B  ROM_STUB.DGN  +  rawimage  DRAGROM.DGN
                                       
 This  method also works for D64ROM2.DGN, which may be either $3F00 bytes  or
 the full $4000 bytes.
 
 Another alternative is to transfer the ROM using a `bit banger' serial  link
 (for  Tandy  CoCo  or  Dragon 64 owners). This method is  described  in  the
 documentation for CoCo2. If you have a ROM image suitable for use  with  the
 CoCo2  emulator  then  you  can  use that ROM file  with  PC-Dragon  without
 modification. To do this just copy the file into your PC-Dragon directory or
 CARTRIGE sub directory.
 
 Please  be  aware  that  the ROM software is copyrighted  by  Microsoft  and
 therefore must not be distributed.
 
 
 
 4     Epilogue
 
 
 
 4.1   Standard Disclaimer
       
 This  program is released as freely distributable charityware. The  software
 is  supplied `as is' with no guarantee of correctness or fitness for purpose
 either  explicit or implied. The author hereby disclaims all  responsibility
 for losses incurred through the use of this program and the advice given  in
 this  manual.  By  using the program you are deemed to have  accepted  these
 conditions of use.
 
 You  may copy and distribute the program freely so long as the software  and
 documentation  remain  unchanged. There is no  fee  payable  for  using  the
 unregistered  version of the software. If the program  is  obtained  from  a
 distribution  service then no additional charge may be made  for  PC-Dragon.
 Software vendors are not permitted to sell PC-Dragon except by mail-order or
 as  part of a CD-ROM archive. If you use PC-Dragon to develop or demonstrate
 software then please acknowledge this in your credits or documentation.
 
 Special  restrictions  apply to the included source code.  Please  read  the
 README.TXT  file in the SOURCE directory if you have the registered  version
 of PC-Dragon.
 
 
 
 4.2   How To Contact The Author
       
 I  welcome all comments and bug reports concerning PC-Dragon. Please contact
 me  by  electronic  mail  at  address burginp@lgcp.logica.com.  If  this  is
 impossible then please contact me by post at the following address:
      
                                Paul Burgin
                                49 Keats Avenue
                                Redhill
                                Surrey
                                RH1 1AF
                                England
      
 
 4.3   How And Why You Should Register
       
 If  you like PC-Dragon and use it regularly then please show your support by
 registering. The registration charge is only 10, US $20 or 30DM, from which
 all proceeds are donated to Oxfam (except for a contribution towards postage
 for  overseas  orders). Your donation can therefore help to save  lives  and
 relieve suffering in less fortunate parts of the world.
 
 To  register simply send your payment (UK cheque, international money order,
 or  cash  by  registered post) together with your name and  address  to  the
 postal address given above. In return you will receive a disk containing the
 latest version of the emulator together with the complete C source code  for
 the  emulator (315K, suitable for Turbo/Borland C++). Please state the  disk
 size that you require. A printed copy of this manual is not included in  the
 package.
 
 The right to revise or withdraw the terms of this offer are reserved. Please
 check  the  document date and write first to confirm the price or  terms  in
 case  of  doubt. I am no longer supplying unregistered versions of PC-Dragon
 by mail order so for these please contact NDUG or an FTP site/bulletin board
 which carries the updates.
 
 As an alternative to registration you are gratefully encouraged to donate an
 amount that you think appropriate for your usage of PC-Dragon directly to  a
 humanitarian  charity of your choice. But no political or  religious  causes
 please, in order to keep the `Charityware' ideal universal.
 
 
 
 4.4   The CoCo2 Emulator
       
 CoCo2 is an excellent freeware Dragon and Tandy CoCo II emulator written  by
 Jeff  Vavasour. It emulates a different range of features to  PC-Dragon  and
 also  executes programs much faster. If you do not already have it then look
 for  `coco2-14.zip'  at your favourite BBS or SimTel mirror  FTP  site.  The
 emulator  can also be registered to receive Jeffs new CoCo III  emulator  in
 addition to CoCo2.
 
 A  version  of  CoCo2  has  been  licensed  by  the  author  for  non-profit
 distribution  by the National Dragon Users Group. The CoCo III  emulator  is
 not  freely  distributable  and is not available  from  the  group  (or  any
 software repository).
 
 
 
 4.5   The National Dragon Users Group
       
 The  National  Dragon  Users Group is an active user  group  for  users  and
 enthusiasts of Dragon and Tandy CoCo computers. It is based in  the  UK  but
 has members from all over the world and new members are always welcome.
 
 If you're enthusiastic towards the Dragon or Tandy CoCo then why not keep in
 touch with other users and help to keep the group alive and by joining NDUG?
 As  a  member  you could purchase the latest commercial, group  and  members
 programs, gain access to a panel of expert volunteers on the help line,  and
 read  all  the latest news, views and reviews in the bi-monthly  newsletter.
 Perhaps you would even like to write some newsletter articles yourself?
 
 A  years  membership is still only 8 for the UK, which represents excellent
 value  for  money. Please drop me a line if you would like further  details.
 NDUG  is also the official distributor for the unregistered version  of  PC-
 Dragon.
 
 
 
 4.6   Dragon E-Mail List
       
 The  Dragon e-mail list has been running for nearly a year and now has  more
 than  20 subscribers. If you would like to be added to the distribution list
 please contact me at the address given on the previous page.
 
 There  is also a mailing list for Tandy CoCo users. To be added to the  list
 send the message `subscribe coco' to listserv@pucc.princeton.edu.
 
 
 
 4.7   Acknowledgements
       
 I  would  like  to thank Jeff Vavasour, Graham Kinns, Keiran Anscomb,  David
 Linsley  and everyone else who has provided information and feedback  during
 the  development of PC-Dragon. Special thanks also to Gerton Lunter for  the
 ReadVoc  utility  and the circuit diagram for the parallel interface  cable.
 Thanks to Lee Hamel for the keyboard interrupt code.
 
 
 
 4.8   Legal Bits And Pieces
       

 Dragon, Dragon 32 and Dragon 64 were once trademarks of Dragon Data Ltd.

 Tandy and Tandy CoCo are trademarks of the Tandy Corporation.

 Acorn and Archimedes are trademarks of Acorn Computers.

 Microsoft, MS-DOS, MS-Windows and QBasic are trademarks of Microsoft Corp.

 IBM is a trademark of International Business Machines Ltd.

 SoundBlaster Pro is a trademark of Westpoint Creative Ltd.

 Compusense is a trademark of P.S.E. Computers.

 Amiga is a trademark of Commodore International.

 ReadVoc and the cable diagram are the work and copyright of Gerton Lunter.
 
 

 Similar trademarks apply in other countries.
 
 
 
 5     Appendices
 
 
 
 5.1   Appendix A: Table Of Emulator Services
       
 
 
  NUMBER | DESCRIPTION OF SERVICE
 --------+-------------------------------------------------------------------
     0   | INSTALLATION/VERSION CHECK
         |  Return:         A = number of last service supported
         |                  X = $5043 signature
         |                  Y = PC-Dragon version (major, minor)
 --------+-------------------------------------------------------------------
     1   | CLOSE DOS FILES
 --------+-------------------------------------------------------------------
     2   | PC CURSOR CONTROL
         |  Params:   A b6-b0 = 0 off, 1 on (solid),     >1 on (underline)
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
     3   | LOWER CASE CONTROL
         |  Params:      A b0 = 0 disable,               1 enable
         |               A b1 = 0 do not refresh screen, 1 refresh screen
         |               A b7 = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
     4   | JOYSTICK EMULATION CONTROL
         |  Params:   A b6-b0 = 0 analogue,              >0 digital
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
     5   | GET/SET TEXT MODE COLOURS
         |  Params: A b0      = 0 do not refresh screen, 1 refresh screen
         |          A b7      = 0 change,                1 do not change
         |          X b15-b12 = new foreground colour in 'screen 0,0'
         |          X b11-b8  = new background colour in 'screen 0,0'
         |          X b7 -b4  = new foreground colour in 'screen 0,1'
         |          X b3 -b0  = new background colour in 'screen 0,1'
         |  Return:         X = previous values; eg. BLK, GREEN, BLK, BROWN
 --------+-------------------------------------------------------------------
     6   | GET/SET GRAPHICS MODE COLOURS
         |  Params:  A b0     = 0 'pmode 0'    colour set, 1 'pmode 1'
         |           A b1     = 0 'screen 1,0' colour set, 1 'screen 1,1'
         |           A b2     = 0 do not refresh screen,   1 refresh screen
         |           A b7     = 0 change,                  1 do not change
         |           U b15-b8 = EGA colour for all of Dragon '00' bit pairs
         |           X b15-b8 = EGA colour for '0' of Dragon '01' bit pairs
         |           X b7 -b0 = EGA colour for '1' of Dragon '01' bit pairs
         |           Y b15-b8 = EGA colour for '1' of Dragon '10' bit pairs
         |           Y b7 -b0 = EGA colour for '0' of Dragon '10' bit pairs
         |           U b7 -b0 = EGA colour for all of Dragon '11' bit pairs
         |  Return:         U = previous values for 00 and 11; eg. GREEN, RED
         |                  X = previous values for 01; eg. YELLOW, YELLOW
         |                  Y = previous values for 10; eg. BLUE, BLUE
 --------+-------------------------------------------------------------------
     7   | GET/SET GRAPHICS BORDER COLOURS
         |  Params:  A b0     = 0 do not refresh screen,   1 refresh screen
         |           A b7     = 0 change,                  1 do not change
         |           X b15-b8 = EGA colour for border in 'screen 1,0'
         |           X b7 -b0 = EGA colour for border in 'screen 1,1'
         |  Return:         X = previous values; eg. GREEN, WHITE
 --------+-------------------------------------------------------------------
     8   | GET MOUSE POSITION AND BUTTON STATUS
         |  Return:      A b0 = 0 left   button not pressed, 1 pressed
         |               A b1 = 0 right  button not pressed, 1 pressed
         |               A b2 = 0 middle button not pressed, 1 pressed
         |                  X = mouse x position
         |                       (range 0 to 31  in text mode)
         |                       (range 0 to 255 in graphics mode)
         |                  Y = mouse y position
         |                       (range 0 to 15  in text mode)
         |                       (range 0 to 191 in graphics mode)
         |              ERROR = 1 if no mouse driver found
         |  NB: $FF00 is added to X or Y if pointer lies beyond screen edge.
 --------+-------------------------------------------------------------------
     9   | EXIT TO DOS
 --------+-------------------------------------------------------------------
    10   | MOUSE POINTER CONTROL
         |  Params:   A b6-b0 = 0 pointer off,           >0 pointer on
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
         |              ERROR = 1 if no mouse driver found
         |  NB: Always turn mouse pointer off before changing video mode.
 --------+-------------------------------------------------------------------
    11   | GET CASSETTE STATUS
         |  Return:         A = 0 failed, 1 ready, 2 reading, 3 writing
 --------+-------------------------------------------------------------------
    12   | GET SAM INFORMATION
         |  Return:         A = map mode (0 or 1)
         |                  B = emulator resolution (0 to 15)
         |                  X = screen base address
         |                  Y = screen end address
 --------+-------------------------------------------------------------------
    13   | GET PC DATE AND TIME
         |  Return:         B = mins
         |                  A = hours
         |                  X = day number
         |                  Y = month
         |                  U = year
 --------+-------------------------------------------------------------------
    14   | ILLEGAL INSTRUCTION CONTROL
         |  Params:   A b6-b0 = 0 pause emulator,        >0 ignore
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    15   | FILENAME PROMPT CONTROL
         |  Params:   A b6-b0 = 0 do not prompt,         >0 prompt
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    16   | KEYBOARD TYPE CONTROL
         |  Params:   A b6-b0 = 0 'PC Mode',             >0 'Real Mode'
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    17   | PRINTER CONTROL
         |  Params:   A b6-b0 = 0 file, 1 LPT1, 2 LPT2,
         |                      3 COM1, 4 COM2, >4 disable printer
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
         |              ERROR = 1 if port not available
 --------+-------------------------------------------------------------------
    18   | CRLF TRANSLATION CONTROL
         |  Params:   A b6-b0 = 0 off,                   >0 translate
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    19   | PRINTER INTERACTION MODE CONTROL
         |  Params:   A b6-b0 = 0 basic,                 >0 advanced
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    20   | SERIAL BAUD RATE CONTROL
         |  Params:   A b1-b0 = 0 1200bps, 1 2400bps, 2 4800bps, 3 9600bps
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    21   | IRQ RATE CONTROL
         |  Params:      A b7 = 0 change,                1 do not change
         |                  X = clock cycles per IRQ
         |  Return:         X = previous value
 --------+-------------------------------------------------------------------
    22   | ARTIFACTING CONTROL
         |  Params:   A b1-b0 = 0 off, 1 blue edge, 2 red edge
         |            A b7    = 0 change,                1 do not change
         |  Return:         A = previous state
 --------+-------------------------------------------------------------------
    23   | GET/SET GRAPHICS BORDER COLOURS V2.0
         |  Params:  A b0     = 0 do not refresh screen,   1 refresh screen
         |           A b7     = 0 change,                  1 do not change
         |           X b15-b8 = EGA colour for monochrome 'screen 1,0'
         |           X b7 -b0 = EGA colour for monochrome 'screen 1,1'
         |           Y b15-b8 = EGA colour for 4-colour   'screen 1,0'
         |           Y b7 -b0 = EGA colour for 4-colour   'screen 1,1'
         |  Return:     X & Y = previous values
 --------+-------------------------------------------------------------------
    24   | JOYSTICK DEVICE CONTROL
         |  Params:   A b6-b0 = 0 mouse,                 >0 PC joystick
         |            A b7    = 0 change,                1 do not change
         |                  X = hardware sampling rate (range 0 to 255)
         |  Return:         A = previous state
         |                  X = previous sampling rate
         |              ERROR = 1 if PC joystick not detected
 --------+-------------------------------------------------------------------
    25   | GET FUNCTION KEY ASSIGNMENT
         |  Params:         A = key to read ('#', 1 to 10, or 'A' to 'Z')
         |                  X = address to write text string
         |  Return:        *X = function key string, null terminated
         |              ERROR = 1 if key number not valid
 --------+-------------------------------------------------------------------
    26   | SET FUNCTION KEY ASSIGNMENT
         |  Params:         A = key to change ('#', 1 to 10, or 'A' to 'Z')
         |                  X = address of source text string
         |  Return:     ERROR = 1 if key number not valid
 --------+-------------------------------------------------------------------
    27   | GENERATE SOUND FROM PC SPEAKER
         |  Params:         X = frequency, or 0 for off
         |                  Y = length (in milliseconds), or 0 for infinite
 --------+-------------------------------------------------------------------
      
                                                  b - bit number or bit range
                                                                             
 
 
 5.2   Appendix B: Table Of Configurable Colours
         
    
      
          Text Colours        Background Colours      Graphics Colours
      
      Black               0  Black              0  Black              00
      Green               2  Green              2  Green              02
      Yellow              E  Brown*             E  Yellow             3E
      Blue                1  Blue               1  Blue               01
      Red                 4  Red                4  Red                04
      Buff                7  Buff               7  Buff               07
      Cyan                3  Cyan               3  Cyan               03
      Magenta             5  Magenta            5  Magenta            3D
      Brown               6  Brown              6  Brown              06
      Dark Gray           8  Black*             8  Dark Gray          38
      Light Green         A  Green*             A  Light Green        3A
      Light Blue          9  Blue*              9  Light Blue         39
      Light Red           C  Red*               C  Light Red          3C
      White               F  Buff*              F  White              3F
      Light Cyan          B  Cyan*              B  Light Cyan         3B
      Pink                D  Magenta*           D  Dark Pink          05
      
     
                                          *with flashing foreground text
                                                                                  
      
      
 5.3  Appendix C: Default Function Strings
       
       
       
        Function Key       Command       Function Key        Command

          ALT - F1         cload^m         ALT - F6           line(
          ALT - F2         csave^m         ALT - F7           pset(
          ALT - F3        cloadm^m         ALT - F8          preset(
          ALT - F4         csavem"         ALT - F9          left$(
          ALT - F5         circle(         ALT - F10         right$(
       
       
       
        Function Key       Command       Function Key        Command

           ALT - A           and            ALT - N           next
           ALT - B          gosub           ALT - O            or
           ALT - C          color           ALT - P          paint(
           ALT - D          draw            ALT - Q           edit
           ALT - E          else            ALT - R           run^m
           ALT - F           for            ALT - S           step
           ALT - G          goto            ALT - T           then
           ALT - H          hex$(           ALT - U          return
           ALT - I          input           ALT - V           val(
           ALT - J         joystk(          ALT - W          screen
           ALT - K          poke            ALT - X           exec
           ALT - L         list^m           ALT - Y          inkey$
           ALT - M          pmode           ALT - Z           peek(



                                                                     30/11/94
