--=-=========================-=--
PC-DRAGON 6809 EMULATOR
--=-=========================-=--
Version 2.02
Reference Manual
Copyright 1993-97
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 9
2.2.3 INPUT BOXES 9
2.2.4 NUMERIC INPUT BOXES 9
2.3 FILENAME ENTRY 9
2.4 EMULATION OF HARDWARE AND PERIPHERALS 10
2.4.1 KEYBOARD 10
2.4.2 VIDEO 12
2.4.3 CASSETTE PORT 12
2.4.4 PRINTER PORT 13
2.4.5 JOYSTICK PORT 14
2.4.6 CARTRIDGE PORT 14
2.5 EMULATOR OPTIONS AND MENUS 15
2.5.1 HELP SCREEN 15
2.5.2 TEXT VIEWER MENU 15
2.5.3 FILE MANAGEMENT MENU 15
2.5.4 OPTIONS MENU 15
2.5.5 VIDEO MODE MENU 16
2.5.6 FUNCTION KEY CONFIGURATION 17
2.5.7 CONTROL MENU 17
2.5.8 ASSEMBLER MENU 17
2.5.9 INFORMATION AND CONFIGURATION SCREEN 17
2.6 PROGRAM DEVELOPMENT TOOLS 18
2.6.1 INTEGRATION OF THE EMULATOR WITH AN ASSEMBLER 18
2.6.2 BUILT-IN DEBUGGER 18
2.6.3 EMULATOR SERVICES 20
2.7 ADDITIONAL INFORMATION 22
2.7.1 VIDEO REFRESH INTERRUPT 22
2.7.2 ILLEGAL AND UNDOCUMENTED INSTRUCTIONS 22
2.7.3 SNAPSHOTS 22
2.7.4 BOOTUP SNAPSHOTS 25
2.7.5 SWAPPING 25
2.7.6 FUNCTION KEY ASSIGNMENTS 25
2.7.7 CHANGING EMULATOR COLOURS FROM THE COMMAND LINE 26
2.7.8 CASSETTE FILES 26
3 FILE TRANSFER 28
3.1 OVERVIEW 28
3.2 DRAGON CONVERT 28
3.2.1 EXTRACTING FILES FROM SAMPLED CASSETTES 29
3.2.2 CONVERTING OTHER FILE TYPES 30
3.2.3 CONVERTING FILES FROM CASSETTE FORMAT 30
3.3 COPYCAS UTILITY 31
3.4 WHATIS UTILITY 31
3.5 READVOC UTILITY 32
3.6 HOW TO TRANSFER YOUR ROM 32
4 EPILOGUE 34
4.1 STANDARD DISCLAIMER 34
4.2 HOW TO CONTACT THE AUTHOR 34
4.3 HOW AND WHY YOU SHOULD REGISTER 34
4.4 OTHER DRAGON / COCO EMULATORS 35
4.5 THE NATIONAL DRAGON USERS GROUP 35
4.6 DRAGON E-MAIL LIST 36
4.7 ACKNOWLEDGEMENTS 36
4.8 LEGAL BITS AND PIECES 36
5 APPENDICES 37
5.1 APPENDIX A: TABLE OF EMULATOR SERVICES 37
5.2 APPENDIX B: TABLE OF CONFIGURABLE COLOURS 41
5.3 APPENDIX C: DEFAULT FUNCTION STRINGS 42
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 as well as a few
undocumented characteristics. 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 a
history 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 or CoCo 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.5, 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 CoCo. The emulator will then detect which of the supported
architectures to emulate and provide a PC implementation of that machine.
Note that the different architectures each have different RAM requirements
and emulation speeds. Dragon 32 emulation, for example, requires 48K less
memory than Dragon 64 emulation and also performs approximately 30% faster.
If you have more than one ROM image then you can 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 MS-Windows.
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.TXT Reference manual converted to plain text format.
WHATSNEW.202 List of changes for PC-Dragon version 2.02.
The following example snapshot files are also included:
BOOTSNAP.??? These files allow the emulator to initialise quickly.
DIAGRAM.??? Circuit diagram for the parallel cassette interface
cable.
TETRAS.D96 Unreleased Dragon 32/64 arcade game.
SHANGHAI.D96 Dragon 32/64 oriental patience game.
Note that PC-Dragon archives contain directories which can be unpacked
together with the files, but are optional. A second freeware PC-Dragon
archive is available containing the emulator source code and reference
manual in postscript. The registered version of PC-Dragon contains all files
within a single archive. Once unpacked, the source code for the emulator can
be found in the SOURCE sub directory.
READVOC.COM and the DIAGRAM files are included with permission from Gerton
Lunter. All other programs are the sole work of the author.
The freeware archives may be distributed in complete form only - individual
files must not be added or removed. The registered version must not be
distributed. If you like PC-Dragon and use the freeware version 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 486 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 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 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 cassettes 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 with PC-Dragon).
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 (e.g. sunsite.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 that 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. Dialogue boxes are red windows with yellow text and
generally operate in a consistent manner. All 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
To select items from menus simply press the number key 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 enter a snapshot filename, or to assign a new string to a
programmable function key. When the input box appears the current string
will be highlighted in the box. You can accept this as the new string by
pressing RETURN or replace it by overtyping it. You can also press END (or
UP/DOWN/RIGHT) to append to the old string or BACKSPACE to edit 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. If you
press SPACE then it will be translated to an underscore (this is essential
for the input of function key strings, which translate underscores back to
spaces when they're used).
2.2.4 Numeric Input Boxes
Numeric input boxes behave in the same way as text 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 enter the current value of a register.
2.3 Filename Entry
A number of emulator functions prompt for a filename to be entered. Full or
relative path names can be used, or if you give just a 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 must give a "." at the end of the name to prevent the emulator from
adding the default extension.
When opening files for output the emulator will not overwrite existing files
without confirmation.
The following are the default extensions and optional sub directories used
by PC-Dragon:
+---------------+--------------------------+--------------------+
| File Type | Default Extension | Sub Directory |
+===============+==========================+====================+
| CARTRIDGE | DGN | CARTRIGE |
+---------------+--------------------------+--------------------+
| SNAPSHOT | PAK or D32/D64/D96/CCO | SNAPSHOT |
+---------------+--------------------------+--------------------+
| | | CASSETTE |
| CASSETTE | CAS | CASSETTE\GAMES |
| | | CASSETTE\ARCHIVE |
+---------------+--------------------------+--------------------+
| SCREENSHOT | Derived from current | - |
| | display mode. | |
+---------------+--------------------------+--------------------+
| SOURCE FILE | A09 | - |
+---------------+--------------------------+--------------------+
| MOTOROLA FILE | S19 | - |
+---------------+--------------------------+--------------------+
2.4 Emulation Of Hardware And Peripherals
2.4.1 Keyboard
There are two modes of keyboard emulation available with PC-Dragon. These
are `Real Mode' and `PC Mode'. `PC Mode' is the default. It is also used
internally by the emulator when dialogue boxes are displayed.
In `PC Mode' keyboard input is passed from the emulator to the emulated
machine by breakpointing the installed operating system ROM and returning
the character code equivalent to the PC key pressed. This method works well
for most BASIC software and some machine code software, and also allows the
PC to buffer input before it is required by the Dragon. This facilitates the
provision of the history 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
- thus some key combinations produce unexpected results on the screen due to
the differences between the PC and Dragon keyboards.
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 tries to access the keyboard 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 the EDIT command).
CURSOR KEYS Dragon cursor keys.
CAPS LOCK Dragon caps lock (SHIFT + 0 key).
The following keys apply only to `PC Mode':
SHIFT + F1 to F4 SHIFT + Dragon cursor keys.
SHIFT + TAB ESC key (as used by the EDIT command).
The following keys apply only to `Real Mode':
ALT + CURSOR KEYS SHIFT + Dragon cursor keys.
ALT + ESC ESC key (as used by the EDIT command).
`[' 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.
History 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 ALT-G for `GOTO', ALT-
N for `NEXT' and ALT-R for `RUN [RETURN]'.
These additional facilities are implemented at the lowest level of keyboard
handling performed by the emulator, which enables all key sequences to be
simulated whether they are input for the Dragon or function keys handled by
the emulator.
2.4.2 Video
PC-Dragon uses the PC 40 column text mode to emulate the Dragon text mode,
with IBM approximations to Dragon graphics blocks used to simulate low
resolution graphics. Graphics modes are emulated using EGA 16 colour
graphics, with all 56 of the Dragon graphics modes fully implemented. A 2-
bit encoding scheme is used for all modes, with separately configurable
colours for the bit pairs 00 (both bits), 01 (left bit), 01 (right bit), 10
(left bit), 10 (right bit), and 11 (both bits).
Semi-graphics modes are not supported and will cause the emulator to display
a 4 colour graphics mode of similar resolution.
The emulator supports optional artifacting in black and white graphics
modes. This may be enabled either by using the /AR and /AB command line
options or by using the display options menu. The emulator then imitates the
red/blue blur exhibited by NTSC televisions. This facility is useful for
Dragon emulation as well as CoCo emulation since many Dragon programs have
been imported from the USA where the effect is sometimes used to an
advantage. Examples of games which are much improved by turning on
artifacting are Mr Dig, Zaxxon, The Vortex Factor and Shenanigans.
Software which uses fast mode switching techniques to achieve special
effects (such as parts of Rommels Revenge, Time Bandit, 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. The `virtual cassette' files contain exact same data that would be on
a cassette and are given the extension CAS.
To use cassette files simply type the Dragon commands exactly as you would
on a real machine (e.g. `CSAVE', `OPEN', `CLOADM'). A dialogue box will then
appear prompting you to enter the name of the virtual cassette file to use.
Type in the filename and press RETURN.
The cassette will remain accessible until the end is reached, until the
Dragon attempts to open the cassette 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 be disabled by using the general options menu or the
/NN command line option. The default name will then be used unless an error
is encountered.
When searching for virtual cassette files, the emulator will optionally use
sub directories CASSETTE, CASSETTE\GAMES and CASSETTE\ARCHIVE below your PC-
Dragon directory. The CASSETTE sub directory is read/write whereas
CASSETTE\GAMES and CASSETTE\ARCHIVE 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. If any
parallel/serial conversion of data is required then it 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 which port is 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 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 a standard
configuration/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 then (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 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 incomplete byte is assumed lost and is discarded.
2.4.5 Joystick Port
PC-Dragon provides emulation of the Dragon joysticks using either the
keyboard, mouse or PC joystick. By default a mouse is used, but the joystick
menu (F4, 4) or /JOY option may be used to select the PC joystick instead
(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 can 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 sampling rate 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 may
or may not automatically execute depending on how they were designed. Bootup
snapshots (these are introduced in section 2.7.4) prevent cartridges from
automatically executing (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 (e.g. 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. As an alternative to the
DGN format, cartridges may also be used in snapshot format (see section
2.7.3).
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 the display, or 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 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 options on the file management menu allow you to load programs
in cartridge (DGN) or Motorola S-record (S19) format into memory. These
files will not automatically execute upon loading.
2.5.4 Options Menu
Press F4 to access the options menu. From here you can select further menus
to change the current PC-Dragon configuration.
Options accessible from these menus may also be changed by using the command
line when you start the emulator, using PC-Dragon programmer services
(except for options relating to snapshots), or chosen as default by placing
the command line text in file PCDRAGON.CFG. A summary of the available
command line equivalents may be obtained by typing `DRAGON /?' or `DRAGON
/H'. You can also use the U*IX style `-' rather than `/' to specify options.
Comments may be included in the configuration file by prefixing them with
`#'.
Press `1' to configure the keyboard mode, enable or disable the cassette
filename prompt, instruct the emulator to ignore or pause upon encountering
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 sampling
rate.
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, alter the portability designation saved with snapshots, and to
allow or inhibit the loading of emulator options, the debugger state, and PC-
Dragon `extensions'.
Press `6' to change the Dragon 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 colours or 4 colour mode
colours the pixel colours are configured based on a 2-bit encoding scheme
(see section 2.4.2).
Once the item that you wish to change has been selected a window will appear
which shows the available colours. The current colour is indicated by `*'.
Select a new colour by pressing `1' to `9' or `A' to `F' (or press ESC,
RETURN or SPACE to leave the colour unchanged).
2.5.5 Video Mode Menu
Press F5 to change the current Dragon video mode. You can then alter the
number of available colours, the palette number in use, the width of
graphics mode pixels, the number of bytes of RAM used for video memory
(together with the pixel width this determines the resolution of graphics
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, or pixel width you can press
CTRL-F5, CTRL-F6 or CTRL-F7.
2.5.6 Function Key Configuration
Press F7 to change the assignment of `PC Mode' function keys. With the F7
menu displayed press the key that you wish to change (without ALT) and then
enter the new text string to be assigned to that key. To assign a string to
F6 press `#' (after doing this 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 in fact applies to all emulator control keys, but only when `PC Mode'
keyboard emulation is selected).
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 built-in debugger.
Accessing the control menu discards any key presses which are queued 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 run-time information such as the current video mode.
Included on the information screen is an estimate of 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 for the display, 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 assembler 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 added. The
source filename may also be specified on the command line when you start PC-
Dragon by preceding it with `@'.
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.
E.g.
DRAGON /IAC:\UTILS\AS9 /IEB.EXE @MY6809.ASM
Warning: 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
can display either the current Dragon text screen, one of two help pages for
the debugger, or a memory dump (beware that selecting the memory dump
display slows down single step execution).
At the bottom of the screen is a small window which displays status messages
and other information.
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 no jumps
or interrupts occur).
The disassembly section also contains a cursor denoted by `>' and `<'. The
cursor is used to mark addresses on a temporary basis and may be moved up
and down the display using the cursor keys, or returned to the address of
the program counter by pressing HOME. If you move the cursor beyond the
bottom of the display then the disassembly will scroll to the next
instruction.
The functions of the debugger are accessed using the following keys:
1 Set breakpoint 1 address. Keys `2' to `6' similarly set the
addresses for breakpoints 2 to 6. These breakpoints are
global, remaining active in addition to any other break
conditions which are activated.
A Display the effective address associated with the current
instruction.
B Set a temporary breakpoint and continue execution.
D Switch to disassembler. Enter the required start address at
the prompt. Then SPACE scrolls the disassembly by a full page,
ENTER and DOWN keys scroll the display by a single line, and
`D' allows a new address to be specified.
E Quick edit memory - does not prompt for a new address.
F Toggle CPU flags. Press additional keys to indicate which
flags 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/edit memory. Enter the start 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 (i.e. a
different execution path is taken).
O Continue execution until a specific opcode is reached. Enter
the required opcode at the prompt (both 8-bit and 16-bit
opcodes can be entered).
Q Continue execution until an RTS instruction is reached.
R Change register values. Press additional keys to indicate
which register you wish to change and then enter the new
value. If you attempt to assign a value larger than 255 to
either A or B 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 is the default use of the window).
V Continue execution until a register changes or 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. To break on any change in the value of
the register simply enter the current value.
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 a 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 can then be 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 memory in the region $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 ; Set-up 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 except on very fast machines, the
frequency of the interrupt does not usually match the 50Hz signal of the
real machine. On a 486DX-33 the frequency is approximately 20Hz.
To help overcome 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 (e.g. 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. E.g. 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 can 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 options/configuration settings. They may
be saved at any time and loaded back later to restore the emulator and
emulated machine to the exact same state. Snapshots created by
emulators/utilities other than PC-Dragon may be loaded into PC-Dragon but
will not necessarily contain as much information as those created by PC-
Dragon; snapshot files may even contain just a memory dump and an execution
address.
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, which is
also suitable for CoCo2 V1.5).
There are also snapshot options to disable the loading of emulator
options/configuration settings from snapshots. The saved length of snapshots
may be changed (but not the start address), and Run Length Encoded (RLE)
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
(although the compression rate achieved is still much less more complex
techniques such as Lempel-Ziv-Welch encoding).
As mentioned above, all snapshots saved by PC-Dragon also contain additional
information which is not used by other emulators. 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. They are incorporated into the
snapshot format in a way which does not affect compatibility with other
emulators.
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 another emulator and 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 base snapshot format does not contain all of necessary PIA data,
many snapshots saved by other emulators cannot be loaded from the command
line without finding that the keyboard is unusable in `Real Mode' (using a
bootup snapshot file can usually correct this problem).
By default PC-Dragon uses the PAK extension when saving a snapshot. PAK is
also used when loading but in addition to this the emulator will look for
snapshots with extensions D32, D64, D96 or CCO as appropriate to the
architecture being emulated. The extension D96 is used to identify snapshots
which are compatible with both Dragon 32 emulation and Dragon 64 emulation.
An option from the snapshot menu can be used to specify the portability of
snapshots prior to using the snapshot save facility. A snapshot can be
designated as non-portable, portable to any Dragon, or portable to any
supported architecture. The `Incorrect ROM' warning message is then
inhibited when the snapshot is reloaded. Note, however, that this feature is
implemented for cosmetic reasons only - the emulator automatically attempts
to repair snapshots which are loaded into incompatible architectures
irrespective of the portability designation.
When loading a compressed snapshot file you do not need to specify that the
snapshot is compressed or set the correct snapshot format version. The
emulator will automatically detect the snapshot format used and uncompress
the data.
If you load a snapshot with a start address of $C000 then PC-Dragon will
assume that it is a cartridge game and will generate an FIRQ in order to
execute it.
To configure the snapshot options from the command line use /SV followed by
the version of CoCo2 that you have (`2', `3' or `4'), /SP followed by the
portability designation to be given to saved snapshots (`N', `D' or `A'),
/SC to enable or disable compression, /SL followed by a number in the range
1 to 65280 indicating the snapshot save length, /SO to inhibit the retrieval
of emulator options when snapshots are loaded, /SD to inhibit the
restoration of the debugger state, and /SX to inhibit PC-Dragon
`extensions'.
If you have the NDUG release of CoCo2 V1.2 then you should select V1.2
format snapshots. For the Internet release of CoCo2 V1.2 and for CoCo2 V1.3
you should select V1.3 format. For CoCo2 V1.4, CoCo2 V1.5 and T3 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 is found then the snapshot is executed immediately rather
than you having to wait whilst the emulated machine performs a cold boot 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 then 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 conventional 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 because SPACE is interpreted as an option separator by MS-
DOS.
If using the command line to change key assignments /F should be followed by
the name of the key to change and the new text string. For the key id 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 virtually any character. E.g. `DRAGON
/FCXcloadmX' is an acceptable command line assigning the BASIC keyword
`CLOADM' to ALT-C and using the `X' character as a delimiter.
Text strings may contain control sequences in addition to printable
characters. To specify a control character simply use the `^' notation. E.g.
`DRAGON /F#!^Q!' configures 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 initial characters you should give the new colour as a
hexadecimal string. For text mode the required hexadecimal string is two
characters. The first represents the foreground colour and the second the
background colour. These are in the range `0' to `F', using the standard PC
text mode colour mappings (see Appendix B).
For graphics mode colours a string of six EGA colour values is required; one
byte for each of the 2-bit values in the scheme described in section 2.4.2.
For border colours a single EGA colour value is required.
2.7.8 Cassette Files
The CAS file type used by the emulator is simply a raw bit stream of
cassette data. Because of this it is simple to append one cassette onto the
end of another by using the MS-DOS `COPY' command (the /B switch must be
given so that a binary copy is performed). For example, the following
command will add the cassette PART2.CAS onto the end of the cassette
PART1.CAS:
COPY /B PART1.CAS + PART2.CAS COMPLETE.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 leaders 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 CoCo ROM:
POKE 146,0 : POKE 147,1 `Reduce number of leader bytes.
`Cannot reduce CoCo motor delay.
Note that if you are planning to use virtual cassette files with the CoCo2
emulator then you shouldn't shorten the leader in this way. Furthermore, if
you intend to use Dragon Convert to transfer files back to a real Dragon
then you might even wish to save programs with longer leaders than normal.
To do this you could type:
For Dragon ROM:
POKE 144,3 `Increase number of leader bytes.
For CoCo ROM:
POKE 146,3 `Increase number of leader bytes.
Cassette files containing machine code programs can be used with either
Dragon or CoCo emulation but are unlikely to execute correctly on both
platforms due to the differences between the ROMs of the machines. BASIC
programs can usually be used with any architecture so long as they are saved
in ASCII format. E.g.
CSAVE "BASICPRG", A
will save a BASIC program that can be used in conjunction with any ROM file.
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 utilities to support the transfer of Dragon cassette and
disk software to the PC environment. 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. The reliability that you can
expect from either method varies according to the equipment used. To
transfer disk software you will need additional Dragon-DOS disk reading
software such as Compusense's PC Convert.
The documentation for CoCo2 also describes methods for transferring software
using a serial cable (suitable for Dragon 64 and 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 the execution speed of the software will be highly dependent on
how powerful your PC is.
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. Note that Dragon Convert will overwrite existing files
without warning.
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
converting the input file. 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 within a single input file will be placed into 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, to retry a block, or to
proceed with the conversion ignoring the error. If you choose to ignore
errors then the converted file is unlikely to be usable, although commercial
software does exist which deliberately contains errors.
If you choose to retry a block then the current conversion parameters (see
below) will appear so that different parameters may be entered. Type the new
values at the prompts or press RETURN to leave one of the parameters
unchanged. Dragon Convert then attempts to load the failed 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 in order to synchronise with the
data. If a leader is not present then this will usually cause data to be
missed - if necessary 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:
o Use the highest available sampling rate for your sound card. At
least 22KHz is required.
o The amplitude of the input data should comfortably span the
available range. Adjust the input volume if necessary.
o 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 removing any noisy parts of the leaders.
o MS-Windows software (E.g. Creative Wave Studio) usually produces
better results than MS-DOS based software.
o 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. This option is usually essential if you use
the /L option.
o The relative volume of the wave form may be specified using the
/Sn command line option, where 0 < n < 126. This option typically
has less impact than the /Wn option, but is usually essential if
you use the /L option.
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. Simply specify the filename of the file to be
converted on the Dragon Convert command line.
If the input file is a cartridge (DGN) file then it will be converted to a
cassette file with a filename taken from the header of the cartridge file.
For all other conversions 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
data reformatting.
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; this enables any file type or proprietary format to be converted.
To use Dragon Convert for this purpose simply specify the filename of a
cassette file on the command line 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 specify /22 on the command line to request a 22KHz output file
instead, or /11 for an 11KHz 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, whilst 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 will also be
rejected.
3.3 CopyCas Utility
CopyCas is a utility to make renamed copies of cassette files. It will
choose an appropriate new DOS filename and copy the data held in the
cassette file renaming the first Dragon file at the same time.
The syntax for CopyCas is as follows:
COPYCAS [/C] dragon-source dragon-destination
The filenames that are required are the Dragon filenames rather than the
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 byte-aligned within 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 CopyCas 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 files of various types. 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 U*IX. All decisions are based
on the contents of the files and not the filenames or extensions.
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 (alternatively, ready-made cables can be ordered from
Brian Gaff, the UK support contact for Gerton Lunter's Z80 emulator). The
circuit diagram for the cable is included with the PC-Dragon - to view it
start the emulator by typing `DRAGON DIAGRAM'. If you decide to construct
the cable then you would be advised to also obtain `z80-302.zip' and utilise
the test and calibration programs supplied with Z80.
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 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 the Internet then you
may be able to download a copy of the ROM from an FTP or WWW site (at the
time of writing there is a link to a site containing the ROMs at
`http://public.logica.com/~burginp/emulators.html#roms').
The procedure for transfer via cassette and the Dragon Convert utility is as
follows:
1) Boot up your Dragon 32, Dragon 64 or 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 CoCo you may optionally use the name TANDYROM rather
than DRAGROM.
3) Boot up your PC and SoundBlaster Pro wave form editor software.
Sample the cassette recorded in step 2 into a file. Alternatively,
use the parallel cable and the ReadVoc utility. A large output
file should result.
4) Now use Dragon Convert to extract the cassette data. Type:
DC DRAGROM
Please don't expect the conversion to work on the first attempt.
You are likely to need to adjust the command line switches until
you find a combination which is suited to your hardware. If you
still have no success then you may wish to try repeating step 3.
Upon successful conversion the file DRAGROM.CAS will be created.
5) Now use Dragon Convert again to convert the cassette data to a
cartridge file. Type:
DC /D DRAGROM.CAS
This should produce the file DRAGROM.DGN in the current directory.
6) If you have a Dragon 64 then you may optionally also wish to
transfer the 64K version of the Dragon ROM. This will enable you
to use the emulator in 64K BASIC mode. The procedure to transfer
this second ROM is much as before. Boot up your Dragon 64 and
switch to 64K mode by typing `EXEC 48000'. Now commit the second
ROM to cassette by typing:
CSAVEM "D64ROM2", &HC000, &HFEFF, 0
Transfer this file to your PC by using the procedure described
before in steps 3 to 5. This time the result should be the file
D64ROM2.DGN, which should be saved in your PC-Dragon directory or
CARTRIGE sub directory.
If you already have your ROM image(s) in DOS format then you can create the
required DGN files from such raw images by using the included header file
ROM_STUB.DGN. You might, for instance, wish to transfer the ROM from your
Dragon to your PC on a floppy disk if you are a disk user. To do this use a
program such as Compusense's PC Convert to transfer the ROM image as a BIN
file.
Raw images can be converted to DGN files using the MS-DOS `COPY' command.
Type:
COPY /B ROM_STUB.DGN + raw-image 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 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.
If you have copies of both the Dragon 32 and Dragon 64 ROMs then you should
name your preferred ROM either DRAGROM or DRAGON, and the other ROM either
D32ROM or D64ROM as appropriate.
Please note that the ROM software is copyrighted by Microsoft and must not
be distributed.
4 Epilogue
4.1 Standard Disclaimer
This 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 freeware version of PC-Dragon freely so long
as the software and documentation remain unchanged. No files may be added to
or removed from the archives. There is no fee payable for using the freeware
version of the software. If the emulator is obtained from a distribution
service then no additional charge may be made for PC-Dragon.
The registered version of PC-Dragon may not be distributed in part or whole.
Special restrictions also apply to the PC-Dragon source code. Please read
the README.TXT file included with the source code.
4.2 How To Contact The Author
I welcome all comments and bug reports concerning PC-Dragon. Please contact
me by e-mail at address burginp@logica.com. If this is impossible then
please contact me by post at the following address:
Paul Burgin
18 Moorcroft Road
Sheffield
S10 4GS
England
4.3 How And Why You Should Register
If you like PC-Dragon and use it regularly then please show your support by
registering. The registration charge is only �10, US $20 or 30DM, and all
proceeds are donated to Oxfam. Your donation can therefore help to save
lives and relieve suffering in less fortunate parts of the world.
To register simply send your payment (UK cheque, international money order,
or cash by registered post) together with your name and address to the
postal address given above. In return you will receive a 3.5" disk
containing the latest version of the emulator together with the complete C
source code for the emulator (315K, suitable for Turbo/Borland C++). The
registered version source code includes the file TITLE.C which is not
supplied in the freeware version. A printed copy of this manual is not
included in the package.
The right to revise or withdraw the terms of this offer are reserved. Please
check the document date and write first to confirm the price or terms in
case of doubt. I am no longer supplying freeware versions of PC-Dragon by
mail order so for these please contact NDUG or an Internet site/bulletin
board which carries the updates.
As an alternative to registration you are gratefully encouraged to donate an
amount that you think appropriate for your usage of PC-Dragon directly to a
humanitarian charity of your choice (no political or religious causes
please). I say this because whilst sending donations to me directly will
encourage the development of similar programs, the primary purpose of
registrations is to raise money for charity rather than to `sell' the
program. PC-Dragon is, after all, far from `crippleware' since even the
source code is freely distributable. Whatever you decide, I thank you for
using the program.
4.4 Other Dragon / CoCo Emulators
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-15.zip' at your favourite BBS or SimTel mirror site.
A version of CoCo2 has been licensed by the author for non-profit
distribution by the National Dragon Users Group. Jeff is also the author of
several other emulators, including a CoCo III emulator which is available by
registration only.
T3 is a multi-tasking multi-session Dragon and Tandy CoCo II emulator that
I'm currently developing. It is written in 80386 assembler, and therefore T3
will run only on 386, 486 and Pentium based PCs. It also requires a VGA
compatible graphics adapter and MS-DOS v4.00. Again it emulates a different
range of features to PC-Dragon. It's execution speed is a little faster than
CoCo2. T3 is available from SimTel mirror sites (additionally, beta versions
are occasionally available at `http://public.logica.com/~burginp/t3.html').
DREaM is a Dragon and Tandy CoCo II emulator written by which runs on any
Amiga with 68020 processor or higher (an A1200 will give 100% speed). There
are two versions, one with Copper support and one without. Features include
sound and joystick emulation, plus support for virtual cassettes and
snapshots. DREaM is available at
`http://public.logica.com/~burginp/emulators.html#dream'.
4.5 The National Dragon Users Group
The National Dragon Users Group is an active user group for users and
enthusiasts of the Dragon and Tandy CoCo. 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 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. Surf to `http://mudhole.ehche.ac.uk/~dragon/info.htm' for
more details. NDUG is also the official distributor for the unregistered
versions of PC-Dragon and T3.
4.6 Dragon E-Mail List
The Dragon e-mail list now has a strong following and a stable address. To
join the list send a message to dragon-list-request@grempc.demon.co.uk.
There is also a mailing list for 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.
The keyboard interrupt code is based on a freeware module written by Lee
Hamel.
4.8 Legal Bits And Pieces
Dragon, Dragon 32 and Dragon 64 were once trademarks of Dragon Data Ltd.
Tandy and Tandy CoCo are trademarks of the Tandy Corporation.
Acorn and Archimedes are trademarks of Acorn Computers.
Microsoft, MS-DOS, MS-Windows and QBasic are trademarks of Microsoft Corp.
IBM is a trademark of International Business Machines Ltd.
SoundBlaster Pro is a trademark of Westpoint Creative Ltd.
Compusense is a trademark of P.S.E. Computers.
Amiga is a trademark of Commodore International.
ReadVoc and the cable diagram are the work and copyright of Gerton Lunter.
Similar trademarks apply in other countries.
5 Appendices
5.1 Appendix A: Table Of Emulator Services
NUMBER | DESCRIPTION OF SERVICE
--------+-------------------------------------------------------------------
0 | INSTALLATION/VERSION CHECK
| Return: A = number of last service supported
| X = $5043 signature
| Y = PC-Dragon version (major, minor)
--------+-------------------------------------------------------------------
1 | CLOSE DOS FILES
--------+-------------------------------------------------------------------
2 | PC CURSOR CONTROL
| Params: A b6-b0 = 0 off, 1 on (solid), >1 on (underline)
| A b7 = 0 change, 1 do not change
| Return: A = previous state
--------+-------------------------------------------------------------------
3 | LOWER CASE CONTROL
| Params: A b0 = 0 disable, 1 enable
| A b1 = 0 do not refresh screen, 1 refresh screen
| A b7 = 0 change, 1 do not change
| Return: A = previous state
--------+-------------------------------------------------------------------
4 | JOYSTICK EMULATION CONTROL
| Params: A b6-b0 = 0 analogue, >0 digital
| A b7 = 0 change, 1 do not change
| Return: A = previous state
--------+-------------------------------------------------------------------
5 | GET/SET TEXT MODE COLOURS
| Params: A b0 = 0 do not refresh screen, 1 refresh screen
| A b7 = 0 change, 1 do not change
| X b15-b12 = new foreground colour in 'screen 0,0'
| X b11-b8 = new background colour in 'screen 0,0'
| X b7 -b4 = new foreground colour in 'screen 0,1'
| X b3 -b0 = new background colour in 'screen 0,1'
| Return: X = previous values; eg. BLK, GREEN, BLK, BROWN
--------+-------------------------------------------------------------------
6 | GET/SET GRAPHICS MODE COLOURS
| Params: A b0 = 0 'pmode 0' colour set, 1 'pmode 1'
| A b1 = 0 'screen 1,0' colour set, 1 'screen 1,1'
| A b2 = 0 do not refresh screen, 1 refresh screen
| A b7 = 0 change, 1 do not change
| U b15-b8 = EGA colour for all of Dragon '00' bit pairs
| X b15-b8 = EGA colour for '0' of Dragon '01' bit pairs
| X b7 -b0 = EGA colour for '1' of Dragon '01' bit pairs
| Y b15-b8 = EGA colour for '1' of Dragon '10' bit pairs
| Y b7 -b0 = EGA colour for '0' of Dragon '10' bit pairs
| U b7 -b0 = EGA colour for all of Dragon '11' bit pairs
| Return: U = previous values for 00 and 11; eg. GREEN, RED
| X = previous values for 01; eg. YELLOW, YELLOW
| Y = previous values for 10; eg. BLUE, BLUE
--------+-------------------------------------------------------------------
7 | GET/SET GRAPHICS BORDER COLOURS
| Params: A b0 = 0 do not refresh screen, 1 refresh screen
| A b7 = 0 change, 1 do not change
| X b15-b8 = EGA colour for border in 'screen 1,0'
| X b7 -b0 = EGA colour for border in 'screen 1,1'
| Return: X = previous values; eg. GREEN, WHITE
--------+-------------------------------------------------------------------
8 | GET MOUSE POSITION AND BUTTON STATUS
| Return: A b0 = 0 left button not pressed, 1 pressed
| A b1 = 0 right button not pressed, 1 pressed
| A b2 = 0 middle button not pressed, 1 pressed
| X = mouse x position
| (range 0 to 31 in text mode)
| (range 0 to 255 in graphics mode)
| Y = mouse y position
| (range 0 to 15 in text mode)
| (range 0 to 191 in graphics mode)
| ERROR = 1 if no mouse driver found
| NB: $FF00 is added to X or Y if pointer lies beyond screen edge.
--------+-------------------------------------------------------------------
9 | EXIT TO DOS
--------+-------------------------------------------------------------------
10 | MOUSE POINTER CONTROL
| Params: A b6-b0 = 0 pointer off, >0 pointer on
| A b7 = 0 change, 1 do not change
| Return: A = previous state
| ERROR = 1 if no mouse driver found
| NB: Always turn mouse pointer off before changing video mode.
--------+-------------------------------------------------------------------
11 | GET CASSETTE STATUS
| Return: A = 0 failed, 1 ready, 2 reading, 3 writing
--------+-------------------------------------------------------------------
12 | GET SAM INFORMATION
| Return: A = map mode (0 or 1)
| B = video 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 Grey 8 Black* 8 Dark Grey 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(
08/06/97