                                       
                                       
                                       
                       --=-=========================-=--
                                       
                            PC-DRAGON 6809 EMULATOR
                                       
                       --=-=========================-=--
                                       
                                       
                                       
                                 Version 2.00
                                       
                               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                                    13
           
           2.4.6  CARTRIDGE PORT                                   14
           
      2.5  EMULATOR OPTIONS AND MENUS                              14
      
           2.5.1  HELP SCREEN                                      14
           
           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                       16
           
           2.5.7  CONTROL MENU                                     16
           
           2.5.8  ASSEMBLER MENU                                   17
           
           2.5.9  INFORMATION AND CONFIGURATION SCREEN             17
           
      2.6  PROGRAM DEVELOPMENT TOOLS                               17
      
           2.6.1  INTEGRATION OF THE EMULATOR WITH AN ASSEMBLER    17
           
           2.6.2  BUILT-IN DEBUGGER                                18
           
           2.6.3  EMULATOR SERVICES                                20
           
      2.7  ADDITIONAL INFORMATION                                  21
      
           2.7.1  VIDEO REFRESH INTERRUPT                          21
           
           2.7.2  ILLEGAL AND UNDOCUMENTED INSTRUCTIONS            21
           
           2.7.3  SNAPSHOTS                                        22
           
           2.7.4  BOOTUP SNAPSHOTS                                 23
           
           2.7.5  SWAPPING                                         23
           
           2.7.6  FUNCTION KEY ASSIGNMENTS                         23
           
           2.7.7  CHANGING EMULATOR COLOURS FROM THE COMMAND LINE  24
           
           2.7.8  CASSETTE FILES                                   24
           
      3    FILE TRANSFER                                           26
      
      3.1  OVERVIEW                                                26
      
      3.2  DRAGON CONVERT                                          26
      
           3.2.1  EXTRACTING FILES FROM SAMPLED CASSETTES          27
           
           3.2.2  CONVERTING OTHER FILE TYPES                      28
           
           3.2.3  CONVERTING FILES FROM CASSETTE FORMAT            28
           
      3.3  COPYCAS UTILITY                                         29
      
      3.4  WHATIS UTILITY                                          29
      
      3.5  READVOC UTILITY                                         29
      
      3.6  HOW TO TRANSFER YOUR ROM                                30
      
      4    EPILOGUE                                                32
      
      4.1  STANDARD DISCLAIMER                                     32
      
      4.2  HOW TO CONTACT THE AUTHOR                               32
      
      4.3  HOW AND WHY YOU SHOULD REGISTER                         32
      
      4.4  THE COCO2 EMULATOR                                      33
      
      4.5  THE NATIONAL DRAGON USERS GROUP                         33
      
      4.6  DRAGON E-MAIL LIST                                      33
      
      4.7  ACKNOWLEDGEMENTS                                        34
      
      4.8  LEGAL BITS AND PIECES                                   34
      
      5    APPENDICES                                              35
      
      5.1  APPENDIX A: TABLE OF EMULATOR SERVICES                  35
      
      5.2  APPENDIX B: TABLE OF CONFIGURABLE COLOURS               39
      
      5.3  APPENDIX C: DEFAULT FUNCTION STRINGS                    40
      
      
      
      
      
      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. 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 recognise and 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  (40
                        pages).
        PCDRAGON.TXT    Reference   manual  converted  to   plain   text
                        format.
      
      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.***      Previously unreleased Dragon 32/64 arcade game.
        SHANGHAI.***    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 DEL 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/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 (also `_',  `]',
                            CTRL-U and `[` 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 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.
      
      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 type 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.
      
      All  options  accessible from these menus may also be  changed  by
      using  the  command  line when you start the emulator,  using  PC-
      Dragon  programmer services, 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.
      
      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 colour 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 pixels in graphics mode, 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.
      
      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 lines 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.
                   
           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  or
      CCO as appropriate to the architecture being emulated.
      
      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), /SC to
      enable  or  disable compression, /SL followed by a number  in  the
      range  1  to 65280 to set 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
      15,  using the standard PC text mode colour mapping (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                 `Greatly increase number  of
                                             leader bytes.
      For Tandy CoCo ROM:
      
                POKE  146,3                 `Greatly 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
      Dragon 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 /2 on the
      command line to request a 22KHz output file.
      
      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]  dragonsource  dragondest
                                       
      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-300.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  Dragon 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,  $20
      or  30DM, from which all proceeds are donated to Oxfam (except for
      a contribution towards postage for overseas orders).
      
      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.
      
      The  terms  and  prices  for all disk offers  may  be  revised  or
      withdrawn  at any time. Please check the document date  and  write
      first  to  confirm  details if in doubt. I am no longer  supplying
      unregistered  versions of PC-Dragon by mail  order  so  for  these
      please contact NDUG or an FTP site or bulletin board which carries
      the updates.
      
      
      
      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' or `coco2-
      13.zip'  at your favourite BBS or SimTel mirror FTP site.  Version
      1.4 is not available at the time of writing but is expected to  be
      released soon.
      
      A  version of CoCo2 has also been licensed by the author for  non-
      profit distribution by the National Dragon Users Group.
      
      
      
      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 above.
      
      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 interface 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 = 5043h 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(
      
