                                       
  -------------------------------------------------------------------------
                                       
            ****   XTRICATOR ZX81 EMULATOR -- Version 1.75  ****
                                       
                        by Carlo Delhez, August 1994
                                       
  -------------------------------------------------------------------------
  This file is in 80-column ASCII format. Use an ASCII editor to read the
  contents, import into your favourite word processor or copy directly to
           your printer (approximately 24 pages @ 60 lines/page).
  -------------------------------------------------------------------------
                                       
  NOTE: A quick reference guide for getting to know XTricator in a short
        time can be found in the file 'Quick_txt'; first-time users may
        find it useful to print that file & follow the instructions there.
  
  
  CONTENTS
  
  Main Features . Registration . Starting XTricator . Commandline
  Qualifiers . Screen Output . Keyboard Facilities . Keyboard Compatibility
  . Pop-Up Menu System . Buttoning . File Management . Printer Driver .
  High Resolution . Incompatibilities . ROM and 8-16k Area . Stopping .
  Clock Frequency . Z80 Emulation . Program Transportation . Other ZX81
  Emulators . General Compatibility . XTricator vs ZX81 . Warranty . About
  the Author . ZX81 Magazines . Release History . Final Notes
  
  
  MAIN FEATURES
  
  XTricator is a no-nonsense ZX81 emulator for Qdos-based system. Here's an
  overview of its main features:
  
  +  the one-and-only ZX81 emulator for Qdos;
  +  suitable for all contemporary and future Qdos-based systems: Trump
     Card, Gold Card, Super Gold Card, QXL, ...
  +  QXL-compatibility with Cache ON and in any screen resolution: the
     XTricator window can even be moved to any position on the QXL screen!
  +  highly compatible emulation of the Z80 microprocessor, including all
     non-official instructions; over 99% of existing ZX81 software will run
     on XTricator without any problems;
  +  written entirely in Assembly Language for compact, fast, reliable and
     efficient code;
  +  supports multitasking with non-destructive windows (Pointer Interface
     required); at ALL times, XTricator will automatically suspend itself
     when put in the background (by whatever method you prefer, e.g. by
     CTRL-C or by buttoning the job); neither screen nor keyboard will
     interfere with other jobs;
  +  extra 8k of RAM in the crash-safe gap between ROM and Basic RAM;
     choose between two inbuilt toolkits to fill up this region, or load
     your own favourite toolkit from disk;
  +  ZX-Printer emulation with direct output to QL-printer, file, etc.
  +  two physical ZX81 keyboard layouts supported;
  +  single-width or double-width ZX81 screen; normal or inverse;
  +  mouse-driven QPAC-compatible menu-system: extensive yet easy to
     understand. Use it either to taylor XTricator to suit your needs or to
     reach the many special features offered by XTricator;
  +  simple keypresses available for Z80 reset, ZX81 SuperBreak, screen
     colour inversion, graphical keyboard help screen, switching hi-res
     modes, etc.; no need to enter the menu system for all that!
  +  extensive disk operating system (QZ-DOS) accessible directly from the
     ZX81 line-editor: change drive, change subdirectory, see files
     directory, LOAD and SAVE programs/data/screens, and MUCH more!
  +  ZX81 program file format compatible to the format used by other major
     ZX81 emulators (PC, Atari); ZX81 programs on tape are easily converted
     to PC files (hence QL files) on disk;
  +  adjustable relative screen refresh rate from 10 Hz up to 200 Hz;
  +  dynamic screen refresh and interrupt rate, automatically adjusted to
     the current emulation speed; this guarantees top-compatibility on the
     fast Qdos systems of the future;
  +  calibrated-speed option to fix operation speed of the emulator fully
     automatically at some preset value, e.g. exact ZX81 speed!
  +  automatic support of 'semi' and real high resolution ZX81 software;
  +  two screendump options to save your ZX81 screen to disk (even while
     ZX81 programs are running);
  +  two help screens are available: one with the ZX81 keyboard layout and
     one with a reminder of the various special keypresses used by
     XTricator;
  +  finally: XTricator is a shareware product, available free of charge
     for the whole Qdos community; registration is optional but highly
     appreciated. Registered users will get a beautiful laserprinted
     manual, a large number of original ZX81 programs on disk, a free
     update and info about later releases.
  
  
  REGISTRATION
  
  XTricator is distributed on a ShareWare basis. You are allowed to make
  copies for other QL users, provided you copy ALL the files and do NOT
  make changes in any one of these files.
  
  If you like to use XTricator, please express your appreciation and
  support my efforts by becoming a REGISTERED user. You will then receive a
  laser-printed copy of this manual, you will be informed about new
  releases, and can update to a more recent version for a small fee to
  cover my costs. Registration also includes conversion of your programs
  from tape to disk, free technical support by the author and the
  possibility to obtain a custom-made version of XTricator to suit your
  specific hardware configuration. Additionaly, you get access to a huge
  ZX81 software library (hundreds of programs available already).
  Registered users will receive the first three disks out of the series
  (containing 240 original ZX81 programs in total!) and can obtain
  successive disks against cost-price. All programs on the disks are tested
  on XTricator and documented in separate text files.
  
  To become a registered XTricator user, send a EuroCheque worth NLG 60
  (Dutch Guilders) or NLG 60 in cash, plus a note stating your name and
  address to me (my address can be found at the bottom of this document).
  The most recent version of XTricator on a 3.5" 720k floppy (3M-brand), a
  laser-printed copy of the manual and the library disks will be dispatched
  you.
  
  Important: For cheques other than EuroCheques, please add NLG 20 for bank
             service costs. If you wish, you may also send cash
             (banknotes!) in a currency other than Dutch Guilders, but
             please use an acceptable rate of exchange and add the
             equivalent of NLG 10 for my exchange costs. Thank you.
  
  DUTCH USERS ONLY: Betaling van het registratie-bedrag vanuit Nederland
             kan ook via een giro-overschrijving. Stort het bedrag (60
             gulden) op rekening 2438038 t.n.v. C. Delhez, Steenbergen,
             onder vermelding van 'XTricator registratie'. U krijgt het
             complete pakket binnen twee weken na ontvangst thuisgestuurd.
             Om zeker te zijn van een correcte (en vooral snellere)
             afhandeling, verdient het de aanbeveling mij ook middels een
             briefkaart, met vermelding van Uw naam en adres, over Uw
             bestelling te informeren.
  
  
  STARTING XTRICATOR
  
  For running XTricator, the following hardware and software is required:
  
  + A QL (or clone) with at least 300k of free RAM memory to store the
    program and for allocation of the required work space. XTricator
    doesn't check memory while allocating it, so if insufficient memory is
    available, a QL crash may result.
  
  + The Pointer Interface environment for the XTricator QPAC-compatible
    menu-system as well as to have maximum flexibility in MultiTasking.
  
  + Toolkit-II by Tony Tebby is optional, but highly recommended.
  
  Compatible hard- or software is ofcourse allowed as well. Obviously, for
  reasons of copyright, the Pointer Interface and Toolkit are not included
  in the XTricator package.
  
  XTricator works fine in all resolutions of the QXL (and with cache on).
  Initially, the XTricator screen is put in the top left-hand corner of the
  QXL screen; the user may change the position via the menu-system.
  Moreover, XTricator has some special provisions to cope with the bugs in
  early releases of SMSQ. XTricator does not (yet) work on SMS2-based
  systems because of the much deviating screen layout.
  
  Before starting XTricator, make sure Toolkit-II and the Pointer Interface
  are present (or create a simple boot-program to do this; you could, for
  example, edit the file 'XTricator_Xample_Boot'). Now type:
  
         EX FLP1_XTRICATOR_EXE
  
  (or use an equivalent hotkey/button-command when you are using the QJUMP
  extended environment.)
  
  This will start XTricator, first showing a title page with some general
  information. After 5 seconds, the title page disappears and the screen
  goes white with horizontal dark-red bars at the bottom and at the top.
  You should also hear a friendly beep. The white region represents the
  main ZX81 screen. It remains white for a short while. In this period the
  ZX81 memory is cleared, the System Variables are initialized and the ZX81
  Display File is expanded to full size: a pause like this also happens
  when you switch on an ordinary ZX81 with more than 3.25k of RAM. Finally,
  the famous inverse-K-cursor appears and XTricator is ready for use.
  
  Before typing anything, return to SuperBasic by pressing CTRL-C. Now type
  the command JOBS. You'll see that XTricator consists of three jobs, viz.:
  
  + XTricator : This is the main part of the emulator, performing the
    actual translation from Z80 to MC68000 code, refreshing the screen at a
    regular rate, reading the keyboard, coping with file requests etc.
  
  + XTr_Guard : This job 'guards' the existence of XTr_Vita.
  
  + XTr_Vita : The spirit of XTricator; as soon as this job is removed,
    XTricator kills itself (more about that later).
  
  These jobs have priorities 127, 1 and 0, respectively. Contrary to older
  versions of XTricator, it's not advised to change these priorities; just
  for fun, try:
  
         SPJOB XTR_VITA,127 : JOBS
  
  Besides the above three jobs, also a 50 Hz interrupt has been linked to
  keep track of the ZX81 internal clock (Frames, address $4034). Because of
  this interrupt, keep in mind NEVER to delete either the 'XTricator' or
  the 'XTr_Guard' job. The ONLY proper way to stop XTricator from outside
  the program is
  
         RJOB XTR_VITA       ( or equivalent )
  
  As soon as you switch to XTricator by means of CTRL-C, XTricator will
  kill itself, closing all channels, releasing its work-space and also
  unlinking the 50 Hz interrupt. Any other way of removing XTricator will
  most likely crash your QL.
  
  Having read all this, switch back to the ZX81 screen (use CTRL-C) and
  start having fun!
  
  
  COMMANDSTRING QUALIFIERS
  
  Instead of starting XTricator as described above, it is also possible to
  add a commandstring with one or more qualifiers so as to influence the
  initial settings of XTricator (TK-II required!). A qualifier is a
  single-letter command, preceeded by any one of the characters '-', '+' or
  '/' (there is no effective difference between these three prefixes). The
  commandstring must be passed as follows:
  
         EX XTRICATOR_EXE;<commandstring>        ( or similar )
  
  with <commandstring> a character expression, normally a quoted string.
  The commandstring may contain one or more qualifiers, which may (but need
  not be) separated by one or more spaces. The XTricator commandstring
  interpreter is case-insensitive, so upper or lower case text may be used
  at will. Qualifiers are interpreted left to right, later settings
  superseding earlier settings.
  
  Currently, the following qualifiers are supported:
  
  /I     force inverted screen colour (black paper, white ink); has no
         effect when used twice.
  
  /Rx    select initial contents of 8-16k area:
         /r0 : clear 8-16k area
         /rA : ZX-Assembler-2 in 8-16k area
         /rB : Coral Basic in 8-16k area         <default>
  
  /Smm   select initial size (in kilobytes) of the RAM memory; mm is an
         integer number in the range 1 through 48. The ROM will be patched
         according to the value of 'mm' in such a way that all resets (e.g.
         using USR 0 or CTRL-ALT-ESC) will yield this memory size again.
         Default setting is /s16 (16k of RAM).
  
  /W     force half-wide ZX81 screen display (this was the default screen
         size on older versions of XTricator).
  
  Example:         EX XTRICATOR_EXE;'-i/s25+Ra-w'
  
  starts XTricator with inverse screen, 25k RAM, ZX-Assembler-2 in the
  8-16k area and half-wide screen
  
  Future versions of XTricator will support many more commandstring
  qualifiers in order to to set things like default drives, printer
  redirection etc. Any invalid qualifier in the commandstring will result
  in an error message being printed in #0 or #1 and execution of XTricator
  will be aborted without any QDOS error.
  
  
  SCREEN OUTPUT
  
  At all times, the screen output frequency is automatically related to the
  emulation speed. Default setting of the screen refresh rate is 10 Hz,
  which means that you'll get 10 screen refreshes per second when the
  emulator runs at 100% of ZX81 speed. However, if the emulator would run
  at 30% or 300% of ZX81 speed, you'd get 3 or 30 refreshes per second,
  respectively. XTricator measures its own emulation speed continuously and
  adjusts the screen refresh rate accordingly.
  
  On fast machines, like (Super) Gold Card or QXL, the 10 Hz rate may be
  too dull. Via the menu system (F1, item T, option F), the rate can be
  advanced to 20, 30, 40, 50, 75, 100 or 200 Hz. Suffice to say that higher
  rates will give smoother screen updating at the cost of emulation speed.
  
  The wobbling XTricator logo in the bottom righthand corner of the screen
  helps you to determine the actual refresh rate: if this text makes one
  oscillation in one second, the screen refresh rate is 12 per second. But
  note: the logo will never make more than 1.25 oscillations per second (to
  avoid hypernervosity), so refresh rates above 15 per second cannot be
  measured this way.
  
  
  KEYBOARD FACILTITIES
  
  A problem for many users may be the keyboard: the ZX81 works with single
  keypress entries (e.g. pressing 'P' gives 'PRINT'). However, it is not
  really necessary to have a ZX81 or ZX81-manual near: just press CTRL-F1
  to see the full ZX81 keyboard lay-out with all characters, keywords,
  functions and graphics. Press ESC to return to the 'normal' ZX81 screen.
  The help screen is a scanned image of the original ZX81 keyboard.
  
  As an example of keyboard operation, take a look at the A-key on the help
  screen. It contains the following symbols:
  
         + the letter A itself
         + the command NEW
         + the command STOP
         + the function ARCSIN
         + a gray block
  
  Pressing the A-key will produce any one of these symbols, depending on
  the current setting of the cursor:
  
         cursor              keypress            effect
         ----------------------------------------------------
         K                   A                   NEW
         K or L              Shift-A             STOP
         L                   A                   A
         F                   A or Shift-A        ARCSIN
         G                   A                   inverse letter A
         G                   Shift-A             gray block
  
  The K-cursor (Keyword) always appears at the beginning of a command line
  and after the THEN keyword; the L-cursor (Letter) appears elsewhere. The
  F- and G-cursors (Function and Graphics) can be activated by the user by
  pressing Shift-Enter and Shift-9, respectively.
  
  The default XTricator screen colour is black characters on a white
  background, which is well suited for playing games. For text handling, I
  think the inverse is more comfortable for the eyes. Just press CTRL-F2 to
  change the display from black on white to white on black and vice versa.
  
  Another non-standard keyboard function is CTRL-ESC, which is in fact a
  'Super Break' facility. Pressing CTRL-ESC will stop the current program
  (BASIC or machine code) and gives error message D after the ESC-key has
  been released. Avoid using CTRL-ESC in the editor-mode or while using the
  Coral Basic TRACE option. In general, it is best to use CTRL-ESC only if
  there is no other way of stopping a program.
  
  CTRL-ESC may cause a ZX81 crash when used from within a machine code
  program. Although this rarely happens, please press CTRL-ALT-ESC (see
  below) to cure the crash.
  
  NOTE: pressing CTRL-ESC in the regular ZX81 editor will cause a 'keyboard
        lock'; please press CTRL-ESC once more to re-activate the keyboard.
        In the CBI editor, CTRL-ESC merely produces a Space.
  
  A full ZX81 system reset (RST 0) can be obtained by pressing
  CTRL-ALT-ESC. This refreshes the ZX81 ROM area (i.e.: the default
  contents of the 0-8k area are restored), and a RST 0 is executed (i.e.:
  RAMtop is set to 32768 and the bottom 16k of RAM is cleared). This is the
  safest way for recovering after some crash or for just restarting the
  ZX81. Note that the 8-16k area and the top 32k of RAM are not altered in
  any way.
  
  If you are working with a Hi-Res program, there is an easy to way to
  switch from the Hi-Res screen to the normal ZX81 screen (e.g. to type a
  command or to view an error message). Press CTRL-F3 to toggle between
  both screens. If you wish to quit Hi-Res altogether, it is advised to use
  CTRL-ALT-F3 instead. This will tell XTricator that the Hi-Res is not
  needed anymore. Please refer to the section "High Resolution" for more
  details.
  
  The CTRL-keypresses should always work IMMEDIATELY, whatever the ZX81 is
  doing at that moment (but not during QZ file command handling). A
  friendly beep will be generated when the keypress is recognised by
  XTricator; you can then safely release the key(s) and await the desired
  the result.
  
  ConTRoL Summary:
  
  CTRL-ESC         Refresh ZX81 ROM, set default character set and abort
                   current ZX81 program (BASIC or M/C) with error 'D';
  CTRL-ALT-ESC     Refresh ZX81 ROM and reset ZX81;
  CTRL-F1          Display graphical keyboard help screen (return by ESC);
  CTRL-F2          Invert screen from b/w to w/b and v.v.;
  CTRL-F3          Switch from Hi-Res to Lo-Res and v.v. (temporarily uses
                   the default character set for displaying the lo-res
                   screen but does not change the I-register);
  CTRL-ALT-F3      End Hi-Res session, resume in Lo-Res and set default
                   character set.
  
  Note that some PC keyboard interfaces for the QL (like QL-Keyboard-90
  from Juergen Falkenberg) have CTRL-F1 and CTRL-F2 mapped on F11 and F12
  of the PC keyboard. These keypresses work just fine with XTricator.
  
  
  KEYBOARD COMPATIBILITY
  
  A lot of effort has been put in interfacing between the QL keyboard and
  the ZX81 keyboard. This is not quite as easy as it may seem. As an
  example, take the comma-character (','). On the QL one has a dedicated
  comma-key, but on the ZX81 one has to press SHIFTed full-stop ('.'). Now
  suppose you press SHIFT-'.' on the QL. What is intended: a comma (as on
  the ZX81) or '>' (as on the QL)? The meaning may well depend on the
  program currently running. In text-handling programs, a '>' seems most
  useful, but for games (which allow you to press many keys at once for
  complicated steering mechanisms) you probably want ',' as a reply.
  Another problem is (for example) SHIFT-'9'. On the ZX81 this is used to
  toggle Graphics Mode, but on the QL keyboard it gives ')'. So, another
  key should be used for Graphics, e.g. SHIFT-'G', but on the ZX81 this
  gives 'LLIST'... Confused?
  
  To overcome all these difficulties, TWO Keyboard Emulator Modes are
  available. These are distinguished by pressing -- or not pressing -- the
  ALT-key, and the default emulator mode (i.e. the one NOT using ALT) can
  be toggled by CAPSLOCK (see little 'LED' at the top of the screen). The
  two emulator modes have many keys in common:
  
  BOTH KEY EMULATOR MODES
  -----------------------
  
  + All unSHIFTed keys will appear as they are shown on the QL keyboard. 
  + ENTER, the Cursor Keys and Space Bar respond as you expect.
  + CTRL-Left functions as RubOut (ZX81 SHIFT-'0').
  + F4 functions as Edit (ZX81 SHIFT-'1').
  + Special keys:  '[' gives '<'
                   ']' gives '>'
                   ''' gives '"'
  
  KEY EMULATOR MODE 1:       if CAPSLOCK OFF : without ALT
  --------------------       if CAPSLOCK ON  : with ALT
  
  All SHIFTed keys will appear as on the ZX81 keyboard.
  
  Examples:        SHIFT-'B' gives '*'
                   SHIFT-'.' gives ','
                   SHIFT-';' gives SHIFT-SHIFT-'X', i.e. just ';'
  
  KEY EMULATOR MODE 2:       if CAPSLOCK OFF : with ALT
  --------------------       if CAPSLOCK ON  : without ALT
  
  All shifted keys will appear as on the QL keyboard. Consequently,
  specific ZX81 keypresses (i.e. SHIFT-'9' for Graphics) do not work.
  
  Examples:        SHIFT-'8' gives '*'
                   SHIFT-'.' gives '>'
                   SHIFT-';' gives ':'
  
  In this mode, some special keypresses are available:
  
                   SHIFT-'6' gives '**'   (instead of '^')
                   SHIFT-'7' gives 'AND'  (instead of '&')
                   SHIFT-'\' gives 'OR'   (instead of '|')
                   SHIFT-'[' gives '<='   (instead of '{')
                   SHIFT-']' gives '>='   (instead of '}')
                   SHIFT-''' gives '""'   (instead of '"')
  
  Note how the QL single quote (''') is converted to a ZX81 double quote
  ('"') whereas the QL double quote is converted to a ZX81 quadruple quote
  ('""'). XTricator effectively doubles the number of quotes!
  
  It is advised to experiment a bit to see which keys do what. In general,
  CTRL-F1 together with Key Emulation Mode 1 should cure most of your
  keyboard problems!
  
  NOTE: the 'delete' key of a PC keyboard connected to the QL via the
        'QL-Keyboard-90' interface should be equivalent to CTRL-Left.
        However, this keystoke often seems to respond as 'left' only. This
        is probably due to the fact that there may a small delay between
        the 'arrival' of the 'CTRL' and 'Left' parts making up this
        keystroke (caused by the interface hardware) and the ZX81 'feels'
        these as separate keystrokes! So: use CTRL-Left instead of
        'delete'! Similar problems may occur with the F11/F12 keys
        (CTRL-F1/F2). The 'delete' key of a QXL does not work at all due to
        a minor 'bug' in SMSQ; also here, use CTRL-Left instead.
  
  
  POP-UP MENU SYSTEM
  
  To make life for XTricator users even easier, a pop-up menu system has
  been implemented. The system of menus offers many facilities by pressing
  down just a few keys. The menu-system was first introduced in XTricator
  1.15 and will be further expanded in future versions. The present version
  of the menu-system is Qpac-compatible and fully controllable by a mouse.
  
  The main menu can be popped up by pressing F1 while the emulator is
  running. A list with the available options is shown. In order to execute
  any one of the options, simply move the arrow-pointer on top of the item
  and then press any mouse button. If you don't have a mouse, use the
  cursor keys and Space or Enter instead. Alternatively, press the key
  printed in front of the desired option and then press any mouse button or
  Space/Enter. If there is a '-' sign after the key, the required action is
  performed immediately. If there is a '>' sign after the key, a new menu
  is popped up to further specify your wishes.
  
  The main menu offers the following facilities:
  
  B  -  back to ZX81; equivalent to pressing ESC.
  
  C  >  change defaults; a sub-menu appears with a list of defaults that
        can be altered. This sub-menu will reappear after you have changed
        any one of the defaults; this makes it easier to change various
        defaults at once; press ESC to return; The sub-menu allows you to
        change the following things:
        
        L  >  LPRINT Output Channel (see section 'Printer Driver')
        
        P  >  Directory Path (equivalent to '*CD:' etc.); when you change
              the directory path (confirm by Enter), the root device will
              be changed accordingly
        
        R  >  Root Device (equivalent to '*USE:'); note: when you change
              the root device (confirm by Enter), the directory path will
              be reset to just the root device!
        
        The existence of the devices is NOT checked by XTricator. An
        underscore at the end of a device name is optional; XTricator will
        add one if you omit it.
  
  D  >  make 32k screendump of ZX81 screen as a QL MODE-4 file (filename is
        requested; overwrite confirmation and full error trapping); this
        screendump can be reloaded from SuperBASIC by a command like:
  
         LBYTES flp1_name_scr,131072   ( or similar )
  
  E  >  make screendump of ZX81 screen as S-file (filename is requested;
        overwrite confirmation and full error trapping); this screendump
        can be reloaded by a QZ-command like:
  
         LOAD "*LOAD:S:NAME:"          ( or similar )
  
  H  -  pop up the keyboard help screen (return by ESC);
  I  -  show general program info (return by ESC);
  K  -  present overview of main keyboard functions (return by ESC);
  Q  >  quit XTricator (confirmation requested);
  
  R  >  reset Z80 (hence ZX81); a submenu appears that lets you select the
        size of RAM needed after the reset: 1k, 16k, 32k, 48k or 'RAMtop
        fixed'. Your choice will cause the ROM to be patched in such a way
        that ALL subsequent resets (for example using USR 0 or
        CTRL-ALT-ESC) will yield this same memory size again. Apply this
        reset-option again to change this size. The 'RAMtop fixed' option
        will retain the present setting of RAMtop and can be used for RAM
        sizes other than the four present in the menu.
  
  S  >  select ROM bank; a sub-menu offers four choices. See section 'ROM
        and 8-16k area' for more details.
  
  T  >  change settings; a sub-menu appears that you can use to view and
        change some relevant emulator settings. These include:
        
        C  -  screen colours: positive or negative. The screen will be
              altered at once. This option is similar to CTRL-F2.
        
        F  -  screen refresh rate: 10, 20, 30, 40, 50, 75, 100 or 200 Hz.
              See section 'Screen Output' for more details.
        
        K  -  no-key IN-value: if a ZX81 program doesn't seem to respond to
              the keyboard, try changing the default value of this
              parameter from $7F into $3F. This may cure the problem.
        
        S  -  calibrated speed: off, 50%, 100%, 150% or 200%. XTricator is
              not only able to measure its own speed, it can also adjust
              its speed to any of these values. For this, a mild
              self-adaptive speed calibration algorithm is used. When
              turned on, the speed is continuously re-adjusted to get the
              best possible results. Obviously, the speed can only be
              adjusted to values smaller than the maximum speed. Therefore,
              this option will only be of use on fast machines like QXL.
              The combination of 100% speed and 50 Hz screen refresh rate
              (option F) results in a very accurate emulation of the real
              ZX81 behaviour.
        
        W  -  screen width: single or double. All 4 screenmodes (lo-res,
              extended-lo-res, semi-hi-res and true-hi-res) can be
              displayed in both widths. The screen will be altered at once.
  
  W  >  move window (useful on QXL only); when you select this option, a
        frame will appear on top of the XTricator window. Use the cursor
        keys to move the frame to any part of the QL screen. Press Enter of
        Space to confirm the new position and contents of the XTricator
        window will be moved. Press ESC to keep the old window position.
  
  In general, the menus disappear by pressing ESC. Only when a text needs
  to be editted (e.g. a filename), ESC won't always work (it will on
  Minerva and SMSQ); in that case, press the up or down cursor key instead.
  
  
  BUTTONING
  
  If you want to put XTricator in a button, it is not necessary to call up
  the keyboard help screen or the menu system first (using CTRL-F1 or F1)
  so as to let XTricator be suspended in the buttoned state. The code of
  XTricator has been written in such a way that is automatically suspended
  once in the background: this results in a significant reduction of
  CPU-time consumption while XTricator is in a buried state. Additionally,
  the program you were running (e.g. a game) is halted completely. As soon
  as XTricator is in the foreground again (e.g. after unbuttoning), the
  program is automatically resumed.
  
  
  FILE MANAGEMENT
  
  Originally, the ZX81 did not have a Disk Operating System. Programs could
  be stored on tape only (at a rather dull rate of 300 baud, taking more
  than 7 minutes to save or load a 16k program). As an alternative, several
  diskdrive systems were introduced by various companies but none of these
  were very successful. People preferred to keep using tapes, and software
  was written to speed-up tape data communication to, say, 6,000 baud (20
  seconds for 16k). This was quite acceptable and a single tape of 60
  minutes could contain up to 2.5 Mb information. However, audio tapes are
  not a very reliable medium and the sequential storage of tapes obstructs
  quick access. As a solution, I used an RS232 interface to connect my ZX81
  to my QL, offering more advanced storage possibilities (diskdrives) and
  being very well suited to act as a fileserver thanks to its multitasking
  capabilities. I wrote this fileserver myself, as well as the software
  needed on the ZX81 to do the communication with the QL. Data could now be
  exchanged at a rate of 9600 baud (13 seconds for 16k) and could be
  accessed in a quick and simple way. I called this serial communication
  system "QZ", which served as an example for the "Disk Operating System",
  QZ-DOS, offered by XTricator.
  
  QZ was first launched December 1989, version 2.0 introduced August 1991,
  version 3.0 introduced December 1992. A detailed description regarding
  the possibilities of QZ is omitted here. If you are interested in QZ,
  please contact me in writing (address at the bottom of this document).
  
  ZX81 filenames are made up in the following way:
  
         <full_name> = <root_device><directory_path><filename>
  with:
         <root_device> :     name of any valid directory device;
                             Examples: 'WIN1_', 'N2_FLP3_' or 'RAM4_'
         <directory_path> :  pathname through subdirectories; subsequent
                             directory levels are separated by underscores;
                             Examples: 'ZX81_GAMES_' or 'UTILS_MCODE_'
         <filename> :        up to 12 characters main name plus underscore
                             and one-letter extension (B, C, L, P, S or V);
                             hence, total length of <filename> is at most
                             14. Examples: 'MAZOGS_P' or 'ZXAS2_C'
  
  So, a <full_name> could be:
  
         'N2_RAM3_GAMES_SHOOT_INVADERS_P'
  or     'WIN1_ZX81_PROGS_DBASE_V'
  
  The total length of <rootdevice> and <directory_path> together may never
  exceed 27 characters. Hence, the total length of <full_name> never
  exceeds 41 characters.
  
  When XTricator has just been started, the default file storage and
  retrieval device is FLP1_, i.e. <root_device>='FLP1_' and
  <directory_path> is empty. For using any other device, issue the 'USE:'
  command (see below) or use the menu system (option C).
  
  To SAVE or LOAD a program to or from the current drive & path, just type
  
         SAVE "<name>"       LOAD "<name>"
  
  which are the equivalents of the QZ commands
  
         SAVE:P:<name>:      LOAD:P:<name>:
  
  LOADing a non-existing program results in Error F. If you SAVE a program
  which already existed, it will simply be overwritten without any user
  confirmation. Loading or saving a file with a NAME of length zero also
  results in error F. 
  
  Since filenames are at most 12 characters long, only the first 12
  characters of the SAVE/LOAD name will be used. Do NOT include INVERSE
  characters in the name, since these are used internally by the ZX81 to
  indicate the end of the filename.
  
  Remember that XTricator does not really have a distinct FAST or SLOW
  mode; programs are always SAVEd in such a way that they are in SLOW mode
  when they are reLOADed on the original ZX81. So, take care when a program
  requires FAST mode for proper operation on the ZX81! For safety reasons,
  the CBI interpreter (when active) is reset after loading a program.
  Again, take care if the loaded program requires (for example) 'NOSTALGIC
  OFF' mode.
  
  To see the ZX81 files in the current drive & path ('FLP1_' by default),
  you must type the QZ command DIR. You can do this either in a LOAD or in
  a SAVE command, but the DIR-command MUST be preceeded by an asterisk
  ('*'). So:
  
         SAVE "*DIR:"        and       LOAD "*DIR:"
  
  will both show a (paginated) directory of the ZX81 files in the current
  drive and path. The '*' indicates that a command is given instead of a
  filename. Consequently, a filename cannot begin with '*'!
  
  Many ZX81 users will be used to typing LOAD "" for loading the first
  program found on tape. Since diskdrives are not sequentially accessible,
  the LOAD "" command cannot be used for loading a file. Instead, XTricator
  will show the disk directory, so:
  
         LOAD ""   is a fast alternative for     LOAD "*DIR:"
  
  Other file handling commands available in XTricator are discussed below.
  
  BACK:  Go one step back in directory path (i.e. one level lower).
         Subsequent subdirectory levels are assumed to be separated by
         underscores, BACK: simply strips off the highest level. No error
         will be generated if you were already at root level.
  
         Example : LOAD "*BACK:"       strips highest subdir level
  
  CD:    Change path from current directory to indicated subdirectory. The
         subdirectory name is appended to the current path. Recall that the
         total length of <root_device>+<directory_path> may not exceed 27
         characters. If you wish to 'CD:' more than one level, use '-' or
         '/' for representing the underscore inbetween successive levels. A
         finishing underscore is optional: XTricator will add it
         automatically if you omit it. Note that CD: will not check if the
         subdirectory exists (i.e. the subdirectory needs not have been
         created by 'MD:').
  
         Examples: LOAD "*CD:GAMES:"             appends 'GAMES_' to path
                   LOAD "*CD:ZX81-DEMO:"         appends 'ZX81_DEMO_'
  
  DEL:   Delete a file; no error is reported when the file does not exist. 
  
         Example:  LOAD "*DEL:P:NONSENSE:"       deletes NONSENSE_P
  
  DIR:   Show (paginated) overview of ZX81 files in current directory; the
         top line always shows the current rootdrive and path. The files in
         on the rootdrive that match the current path and also conform to
         the QZ file format (cf. <full_name>) are shown, together with the
         filelength, date and time. All non-QZ-type files on the current
         drive are omitted. The underscore between main name and extension
         is converted to a period ('.'). Subdirectories of the current path
         are ONLY shown if they were made with the 'MD:' command (see
         there). Subdirectories are indicated by '<DIR>' in the
         length-column. At the end of each page but the last, press 'Q' to
         stop or any other key to view the next page. On the last page, the
         total number of files and the number of kilobytes left on the
         current rootdrive are shown.
  
         Example:  LOAD "*DIR:"        shows directory
         
  KILL-XTR: End the current XTricator job; see section 'Stopping' for more
         details.
  
         Example:  LOAD "*KILL-XTR:"   ends XTricator
  
  LOAD:  Used for LOADing special files (NOT 'P'-files). All the special
         filetypes are supported: 'B' (for 'Basic'), 'C' (for 'Code'), 'L'
         (for 'Lines'), 'S' (for 'Screen') and 'V' (for 'Variables').
  
         Examples:
  
         (1) LOAD "*LOAD:B:VARTEST:"
         deletes all the lines of the current BASIC programs and then
         merges the program in the file 'VARTEST.B'; note that the BASIC
         variables are not influenced! The LOAD:B command always generates
         Error I (data Inserted).
  
         (2) LOAD "*LOAD:C:NAMES:40000:"
         loads the file 'NAMES.C' to address 40000; during LOAD, address
         65535 is never exceeded, so the maximum number of bytes that can
         be loaded is (in this case) 65536 - 40000 = 25536, and similarly
         for other addresses.
  
         (3) LOAD "*LOAD:L:SUBROUTINE:"
         merges the lines in the file 'SUBROUTINE.L' with the current BASIC
         program; if a line already exists, it will be replaced by the new
         line; note that the BASIC variables are not influenced. The LOAD:L
         command always generates Error I (data Inserted).
  
         (4) LOAD "*LOAD:S:READ-ME:"
         loads the file 'READ-ME.S' into the display file; the display file
         must be fully expanded; this is not checked! An 'S' file is always
         793 bytes long.
  
         (5) LOAD "*LOAD:V:DATABASE:"
         clears the entire variables area and LOADs the variables of the
         file 'DATABASE.V'; this is NOT a MERGE facility; the LOAD:V always
         generates Error I (data Inserted).
  
         Please note the significant difference between LOAD:B and LOAD:L.
         LOADing filetypes 'B', 'L', 'P' or 'V' may cause a ZX81 crash if
         there is insufficient memory left below RAMtop to insert the file;
         please check available memory before attempting to LOAD; in case a
         crash occurs, recover with CTRL-ALT-ESC.
  
  MAIN:  Go to main (=root) directory of current device, i.e. the current
         pathname is reset to zero length. The rootdrive remains the same.
  
         Example:  LOAD "*MAIN:"       clears current pathname
  
  MD:    Make (create) indicated subdirectory in current directory. The
         supplied subdirectory name is appended to the current path and
         then created. The path remains unchanged. Recall that the total
         length of <root_device> + <directory_path> may not exceed 27
         characters. If you wish to 'MD:' more than one level, use '-' or
         '/' for representing the underscore inbetween successive levels. A
         finishing underscore is optional: XTricator will add it
         automatically if you omit it. Use 'MD:' only if the root device
         actually supports subdirectories (e.g. a Hard Disk or a diskdrive
         connected to a (Super) Gold Card or QXL).
  
         Example : LOAD "*MD:UTILITIES:"         makes UTILITIES subdir
  
  RD:    Remove indicated subdirectory from current directory. The supplied
         subdirectory name is appended to the current path and then
         removed. The path remains unchanged. Recall that the total length
         of <root_device> + <directory_path> may not exceed 27 characters.
         If you wish to 'RD:' more than one level, use '-' or '/' for
         representing the underscore inbetween successive levels. A
         finishing underscore is optional: XTricator will add it
         automatically if you omit it. An 'in use' error results if the
         subdirectory is not empty.
  
         Example:  LOAD "*RD:TEMPORARY:"         removes TEMPORARY subdir
  
  REMOVE: Equivalent to 'DEL:' - see there.
  
         Example:  LOAD "*REMOVE:P:USELESS:"     removes file USELESS.P
  
  ROOT:  Equivalent to 'MAIN:' - see there.
  
         Example : LOAD "*ROOT:"                 clears current pathname
  
  SAVE:  Used for SAVEing special files (NOT 'P'-files). All special file
         types are supported: 'B' (for 'Basic'), 'C' (for 'Code'), 'L' (for
         'Lines'), 'S' (for 'Screen') and 'V' (for 'Variables'). The
         'SAVE:' command overwrites an existing file with the same name (if
         any) without user confirmation.
  
         Examples:
  
         (1) LOAD "*SAVE:B:PLEASE:"
         Saves all the BASIC lines currently in memory to the file
         'PLEASE.B'; note that system variables, BASIC variables and screen
         are NOT written to file!
  
         (2) LOAD "*SAVE:C:BINARY:20000:8192:"
         Saves 8192 bytes of memory, starting at address 20000, to the file
         'NAMES.C'; The last address of the SAVEd code block may not exceed
         address 65535; in that case an error message is given.
  
         (3) LOAD "*SAVE:L:SECTION:450:780:"
         Saves the lines of the current program with line numbers between
         450 and 780 (both inclusive) to the file 'SECTION.L'; if no lines
         exist is this region, an empty file is created. Note that the
         first line number must be less than or equal to the last line
         number; the last line number is smaller than 10000; the line
         numbers itself need not exist.
  
         (4) LOAD "*SAVE:S:PICTURE:"
         Save the current display file to the file 'PICTURE.S'; an 'S' file
         is always 793 bytes long, i.e. it is assumed that the display file
         is fully expanded.
  
         (5) LOAD "*SAVE:V:DISCOGRAPHY:"
         Save the contents of the variables area (including the CHR$ 128 at
         the end) to the file 'DISCOGRAPHY.V'.
  
  SHOW:  Shows information about the current version of XTricator and
         presents a list of the available QZ commands. Also, the current
         rootdrive and path are printed.
  
         Example:  LOAD "*SHOW:"       presents the information
  
  USE:   Set default device for LOAD, SAVE and QZ file-handling commands.
         The device name may be up to 27 characters in length. If
         underscores are needed in the name, use the '-' or '/' characters
         instead. An underscore at the end is optional: XTricator will add
         it automatically if you omit it. The device MUST be a directory
         driver. This is not checked by the USE: command, but DIR: will not
         work properly if this is not the case. Note that USE: clears the
         current pathname.
  
         Examples: LOAD "*USE:RAM1:"             to use RAM1_ as rootdrive
                   LOAD "*USE:N2-WIN1-"          to use N2_WIN1_
  
  It is allowed to use more than one command in a single LOAD or SAVE. Just
  put a semi-colon (';') in-between two successive commands, e.g.
  
         LOAD "*USE:RAM4:;CD:ZX81/UTILS:;MD:SOURCES:;DIR:"
  or     SAVE "*SAVE:S:SNAPSHOT:;LOAD:C:MACHINE:31000:"
  
  Any non-supported command after the '*' will result in an error report.
  If a standard QDOS TRAP used by the QZ interpreter returns an error, the
  ZX81 screen is cleared, the erroneous command is shown and you are told
  which QDOS error occured. Finally note that string expressions after SAVE
  or LOAD instead of a simple quoted text are also allowed.
  
  NOTE: The file management system writes all information (e.g. directory
        and error messages) directly to the ZX81 screen, NOT to the QL
        screen. For this, it expects a fully expanded ZX81 display file. If
        the display file is not entirely expanded (e.g. after a SCROLL
        statement or with RAMtop below address 19712), you will hear a
        friendly beep and error 4 is displayed, indicating that there is
        insufficient screen space for displaying the required information!
  
  
  PRINTER DRIVER
  
  A simple printer driver is available to emulate the ZX81 printer output.
  By default, printer output is disabled. Printer output can be enabled via
  menu option 'Change Defaults', submenu option 'LPRINT output channel'.
  There you can type any filename or devicename to which printer output is
  to be redirected (e.g. 'FLP1_ZX81_Printer' or 'SER1'). Pressing ENTER
  acts as a confirmation and will open the required channel for output.
  Press the up/down arrow key to escape - printer output will then be
  disabled again.
  
  When sending printer output to file, the file will remain opened until
  you select another file (or device) for printer output. If you want to
  disable printer output alltogether, simply wipe the text in the editor
  (e.g. via CTRL-Shift-Left) and press ENTER.
  
  In case you use SER1 or SER2 for printer output, the required baud rate
  must be set in SuperBasic (before starting XTricator or just before
  printing). The produced output is in ASCII only (no printer control
  codes) and a simple LF (ASCII 10) is given at the end of each line (i.e.
  no CR, ASCII 13).
  
  Inverse-video ZX81 characters are converted to non-inverted ones and ZX81
  graphics symbols are printed as spaces (so you can draw them yourself).
  
  The ZX81 commands COPY, LPRINT and LLIST work as expected. Also, programs
  using the appropriate ROM routines for printing (not Hi-Res!) or programs
  setting bit 1 of address $4001 before using RST $10 function perfectly.
  It cannot be avoided that listings and texts are printed in the awkward
  32-column format.
  
  If you send data to (for example) SER1 whilst no printer is connected,
  XTricator will persistently try to send data anyway (the XTricator logo
  in the bottom of the screen will then be running nervously). In such a
  case, press <ESC> to tell XTricator that no printer is connected. Note
  that this means that printer output will be disabled until you change or
  reconfirm the LPRINT output channel via the menu system.
  
  
  HIGH RESOLUTION
  
  Sir Clive Sinclair himself said that it could not be done...
  
  In 1983, a first attempt to High Resolution on the ZX81 was presented
  when the High Resolution Toolkit by Richard Taylor was marketed. Later,
  companies like Software Farm produced several games in High Resolution.
  Taking a closer look at this 'High Resolution', one can easily see that
  it is not true Hi-Res: for the 256 bit patterns which are possible for 8
  successive pixels, at most 128 are available, i.e. more than half of the
  patterns cannot be used. The result of this Semi Hi-Res may however still
  be quite satisfactory.
  
  XTricator offers four resolution modes:
  
  (1) Low Resolution (LR): normal mode of operation; 32x24 text mode.
  (2) Extended Low Resolution (XLR): used by the program 'Z-Xtricator'; in
      fact 32x192 text mode.
  (3) Semi High Resolution (SHR): used by all other software-based hi-res
      drivers; 256x192 graphics, but the pixels are not entirely
      independently addressable.
  (4) True High Resolution (THR): needs additional hardware on the ZX81
      (but not on the emulator) and is supported by the excellent programs
      HRG7 and HRG8 from Germany; full 256x256 resolution, yet only a part
      of 256x192 can be seen at any time.
  
  All these modes can be viewed in half or full screen width. The THR mode
  supported by Extended Basic Level 3 (which was emulated on older version
  of XTricator) is no longer available.
  
  The appropriate mode is detected by XTricator by trapping a change in Z80
  register I or a change in value of interrupt register IX and browsing
  through RAM in search of the characterically shaped display files or any
  other relevant clues. 
  
  When XTricator is in XLR-, SHR- or THR-mode, the normal ZX81 display
  cannot be seen. Press CTRL-F3 to go to the LR screen and back!
  Alternatively, the Hi-Res screens can be disabled completely by pressing
  CTRL-ALT-F3. This will switch you back to normal Lo-Res and will also set
  the default character set.
  
  As fas as I know, only HRWP (Hi-Res Word Processor) does not function on
  XTricator - and never will (it seems too complicated to be emulated!).
  
  
  INCOMPATIBILITIES
  
  Some programs behave strangely when you RUN them under XTricator.
  Generally, these programs are to blame, NOT XTricator! Some known 'bugs'
  are listed below:
  
  FIGFORTH (Version 1 by Artic) does not seem to work at all. The reason is
    a badly programmed memory test. FIGFORTH checks memory from bottom to
    top. Two conditions should stop the memory check: (1) Non-RAM memory or
    (2) reaching the Stack Pointer. In fact, only (1) is checked, yet in a
    very mysterious way this seems to work properly on a ZX81, probably
    because interrupts change the stack once in a while, which is
    interpreted as non-RAM memory (the memory test itself does not alter
    the stack in any way). Tricky business! On XTricator, interrupts don't
    change the stack and non-RAM memory doesn't exist, so the memory check
    goes on until it overwrites its own code... To get a working copy of
    FIGFORTH, POKE the following numbers at the addresses 17247 onwards: 0,
    0, 57, 24, 11 (all decimal). Then SAVE, type NEW, LOAD again and start
    by GOTO 20. Note that issueing a NEW is essential before LOADing the
    program! A working copy of FIGFORTH can be found on Library Disk #1.
  
  FORTY NINER by Software Farm uses a processor-speed independent delay
    loop at several places in the program. It 'peeks' the low byte of
    Frames, decrements it with a certain value and waits until the low byte
    of Frames reaches this decremented value. As there is a large
    possibility that XTricator is temporarily suspended at the moment that
    the low byte of Frames takes this value, the program may 'miss' the
    value and will have to wait another 5 seconds before the low byte has
    the required value again - this obviously makes the program extremely
    slow. As a solution, break the program by CTRL-ESC at the title page,
    issue the following: POKE 24490,56 and POKE 26707,56 and re-save by RUN
    100. The program FORTYNIN.P on Library Disk #2 has been treated this
    way. Note that screen objects may now appear all on top of each
    other...
  
  
  ROM AND 8-16K AREA
  
  In older versions of XTricator, the ROM was POKEable. This is no longer
  the case in the present version, hence the user cannot change the ROM
  anymore. This makes the emulator less sensitive to buggy ZX81 software.
  
  The 8-16k area is still part of RAM, i.e. it is not POKE- protected. This
  can be nice for using the 8-16k area for machine code utilities that can
  be loaded from disk. At startup, the 8-16k area contains a relocated
  version of the CORAL BASIC INTERPRETER (CBI version 7.0). You can start
  this program by typing
  
         RAND USR 8192
  
  This should give 0/0 in line 22 and a black cursor in line 23. CBI may be
  useful for people with little ZX81 experience since it has both a
  full-entry decoder, full-screen editor and explains error messages on
  request. All usual ZX81 commands are available, as well as 46 new ones
  (including commands for PROCedures with two-way data exchange and
  structured loops). Naturally, CBI was written for the ZX81, but runs
  equally well on XTricator. For more details on CBI, please read the
  separate text file supplied with your copy of XTricator. Two useful
  commands to enter when the black cursor appears are:
  
         ERR MSGS ON         ( explains error messages )
         NOSTALGIC OFF       ( enables full screen editor )
  
  Note that you have to type the letters one-by-one, the spaces are
  optional. The sytem variables of CBI are stored at address 65400 onwards
  (corresponding to address 32730 in the original version). The CBI program
  ends at address 13522, so the part of memory from address 13523 up to
  16383 is free for your own use.
  
  The contents of the 8-16k area can easily be changed by selecting menu
  option 'S' of the main XTricator menu. Then select any of the following
  options:
  
         A : to install ZX-Assembler-2 (ZXA2) in the 8-16k area;
         C : to install Coral Basic Interpreter (CBI) in the 8-16k area;
         R : to refresh the main ZX81 ROM area (0-8k);
         W : to wipe the 8-16k area (zero-filled);
         ESC to leave everything as it was.
  
  Options 'A', 'C' and 'W' do some clever things with the ZX81 system
  variables and will force a break on the current (machine code) program to
  make sure that no crash occurs as a result of the ROM-bank-switching. For
  example, it is allowed to change from the CBI- to the ZXA2-ROM while CBI
  is running! Only error D will occur, no other disasterous effects take
  place. Just one advise: don't change the ROMbank while using the ZXA2
  source editor...
  
  'ZX-Assembler-2' must be started by 'RAND USR 8192'. ZXA2 is a rewrite of
  the ZX-Assembler first marketed by Artic. It is much better in many
  respects. Amongst other things, the following directives have been added:
  ORG, DEFB, DEFW and DEFS. Moreover, ZXA2 can create SELF RELOCATING CODE.
  All you need to do is put an 'ORG 0' directive at the beginning of the
  source code. The resulting object code can be stored at any place in the
  memory map and will always run OK! The version number of ZXA2 can be seen
  by pressing 'V' after having started ZXA2. A manual for ZXA2 will be
  written in the (near) future.
  
  
  STOPPING
  
  There are FOUR ways to end your XTricator session. The first is by
  typing
  
         RJOB XTR_VITA       ( or equivalent )
  
  in SuperBasic and then returning to XTricator by CTRL-C. This will clean
  up the QL, removing all channels, jobs and interrupts owned by XTricator.
  The second way is to use a QZ command from within XTricator; just type:
  
         LOAD "*KILL-XTR:"
  
  which is in fact equivalent to removing the XTR_VITA job. Since this
  requires a lot of typing, there is a third alternative:
  
         LOAD " STOP "
  
  - with STOP typed as a keyword (Shift-'A') - will also end the XTricator
  session. Fourthly, you may pop-up the menu system (F1), use option 'Q'
  and then select 'Y' to confirm that you wish to quit XTricator.
  
  
  CLOCK FREQUENCY
  
  The effective clock frequency can be determined in serveral ways. First
  of all, you can RUN a (long) BASIC program which does not have any INPUT,
  INKEY$, RND, PAUSE or similar commands (i.e. execution time must be fully
  determinate and may not contain processor-independent loops). You can
  then compare the execution time on XTricator to the time which this same
  program requires on a ZX81. The ZX81 runs at 3.2 MHz in FAST mode and at
  0.8 MHz in SLOW mode. Supposing a program on Xtricator takes three times
  longer to execute than on the ZX81 in SLOW, the effective clock frequency
  is (0.8 MHz)/3 = approx. 0.25 MHz.
  
  Another way to find the clock frequency is to use a machine code test
  loop, embracing a single instruction which is executed many (e.g. 65536)
  times. If you then count the number of frames needed (and subtract the
  number of frames needed for just the empty loop) you can get an idea of
  the clock frequency of that specific instruction, provided you know the
  number of T-cycles the Z80 would normally need for that same instruction.
  
  On a normal MC68008-based QL, I found from the latter method specific
  instruction clock frequencies varying between 0.1 and 0.4 MHz. This seems
  to agree with the average (effective) value of 0.25 MHz. (Due to the
  emulation process, the specific clock frequency varies per instruction!)
  With a Gold Card, this number can be increased up to 0.8 MHz, with a
  Super Gold Card to 1.6 MHz, and with a QXL to 3.2 MHz.
  
  
  Z80 EMULATION
  
  As far as I have been able to test, all Z80 instructions are emulated
  correctly: since the ZX81 ROM is the basis for XTricator to function, the
  latter statement must be true. Also, hundreds of ZX81 programs have been
  tested on XTricator and all of them turned out to work without any
  problem! (These programs include (commercially marketed) games and
  utilities in BASIC and in machine code!)
  
  Some brief remarks for Z80 freaks:
  
  + The Half Carry and Subtract flag of the Z80 flag-register (f) are NOT
    emulated. Nearly all Z80 instructions alter these flags, but there is
    only one instruction which uses the result, viz. DAA. Since DAA is used
    only once in the ZX81 ROM and since proper emulation of the Half Carry
    greatly reduces operation speed of XTricator, I think this exclusion is
    a sensible decision. Instead, DAA is emulated by a clever algorithm
    that can trace-back the instruction that has most recently been
    executed and affected the accumulator and allows DAA to work reliably
    in most practical cases.
  
  + HALT waits for an interrupt. Interrupts are not emulated and therefore
    HALT is made equal to NOP.
  
  + Register I points to the ZX81 character set. Default value is I=$1E
    which means that the character set starts at address $1E00 (last half K
    of ROM). If you want to change the characterset, first POKE the new set
    somewhere in memory (at an address which is a multiple of 512 bytes)
    and then alter register I accordingly (so: only even values for I are
    allowed). This will instantaneously change the display. The reversed
    sequence of this procedure will not work the way you would expect! I
    advise not to change the character set present in ROM.
  
  + All memory-changing instructions are protected in the 0-8k area (ROM).
    The reason for this is to protect the ROM against itself! The
    programmers of the ZX81 ROM have made use of the write-protection of
    the 0-8k area for simplifying their code (or is it a hitherto unknown
    bug of the ZX81 ROM?). So, XTricator (which has no write-protection in
    the ROM area) would alter its own code, which is (in general!) a bad
    thing to do. Therefore, the above instructions are emulated such that
    they have no effect in the first 8k of memory. Note that this also
    protects the ROM against a program like MCODER-2, which does the same
    kind of nasty things to the ZX81 ROM-area...
  
  
  PROGRAM TRANSPORTATION
  
  Some trouble is caused by the fact that ZX81 programs were usually stored
  on tape instead of disk. Two solutions are available: firstly, you can
  purchase an RS232 interface for your ZX81, supplied with a comprehensive
  file-server, and send programs directly from ZX81 to QL (and vice versa).
  Secondly, you can send me your tapes (unprotected and of reasonable
  quality only!), and for a small fee per program I will send back a 3.5"
  DS/DD floppy with your programs on it, directly suited for use with
  XTricator.
  
  The first solution is advantageous for two reasons: first of all, you
  have a physical connection between ZX81 and QL and could - for example -
  edit programs on XTricator and run them on the ZX81 (or, again, vice
  versa). Secondly, the file-server (called QZ) works both on the ZX81 (via
  the serial line) and on XTricator. On XTricator, you can use the ordinary
  ZX81 SAVE and LOAD commands, which write programs to disk and read
  programs from disk in a format directly compatible to the QZ file format.
  Additionally, you can pass commands and parameters which are equivalent
  to the set of commands supported by the current QZ version (e.g. DIR:).
  
  For this solution you need a serial interface (plus cable) for your ZX81.
  You'll have to build this interface yourself. The schematic is available
  for free from me. Only three simple TTL chips are needed. Total cost of
  components and circuit board is about NLG 15 (or UK-pound sterling 5, or
  US $ 9). The Fileserver software is ShareWare and consists of a ZX81
  program on tape and comprehensive QL software on a 3.5" DS/DD disk, also
  containing the manual. This software can be obtained from me by sending
  one 3.5" DS/DD disk plus 10 IRCs to cover costs of tape, packing and
  postage.
  
  
  OTHER ZX81 EMULATORS
  
  The QL is not the only computer for which a ZX81 emulator has been
  written. An emulator very similar to XTricator exists for MS/DOS
  machines: it is called "XTender" and is written by myself - see notes at
  the end of this document for more details. If you like to use XTricator,
  you will also like to use XTender because it works exactly the same: even
  keystrokes and file commands are all the same. Also, all ZX81 files can
  be ported from QL to PC and vice versa without problems (you only need a
  disk conversion program like XOVER, ATR driver, MultiDISCover etc.).
  
  For XTender, a tape loading (and saving) utility is now available. This
  makes it very easy to convert programs on original ZX81 tapes to the PC
  (and QL) and vice versa (no ZX81 needed). Write me for details.
  
  An equivalent ZX81 emulator has also been written for the ATARI ST
  computer. I have no personal experience with this emulator, but it seems
  that ZX81 programs available for that emulator can be LOADed directly
  into XTricator and RUN without problems. Note that the files with
  extension '81' on the ATARI emulator are compatible to the 'P' files of
  XTricator. An XTricator user pointed out that it also works fine the
  other way round (this was checked personally by the author of the Atari
  emulator)!
  
  A (probably very fast) ZX81 emulator for the Commodore AMIGA is on the
  'todo' list of Peter McGavin, author of an excellent Spectrum emulator
  for the Amiga.
  
  
  GENERAL COMPATIBILITY
  
  Since the original ZX81 ROM in Z80 code is included (with only a few
  minor changes, of no interest for ordinary use) almost complete software
  compatibility is guaranteed. Almost, since only some VERY specific
  software can obviously NOT be emulated: programs using either standard or
  non-standard input/output ports (e.g. the ear/mic-lines and lines
  connected to external hardware devices not available on the QL such as
  sound-generators or EPROM programmers; note however that the keyboard and
  printer input-lines are emulated correctly), and programs taking over the
  interrupt vector (e.g. ZX81 sprite programs, although the characterset
  can be redefined in the usual way and also Hi-Res is available) are NOT
  supported by XTricator.
  
  Apart from these exceptional applications, ANY program running on the
  ZX81 should ALSO run on XTricator.
  
  
  XTRICATOR vs ZX81
  
  XTricator has some advantages and disadvantages with respect to the ZX81.
  To name just a few advantages: safe housing in a well-stabilized computer
  (none of the tricky business with wobbling RAM packs), full 56k RAM
  available (including POKEable 8-16k area), reliable and fast data-storage
  (no more tapes!), the ZX81 display file can be moved to any part of
  memory without a crash, machine code can also be executed in the top 32k
  of memory (on the ZX81 only the bottom 32k could be used), easy screen
  invert option, quick reset etc. etc. Additionally, XTricator happily
  MultiTasks, so you can run several copies of XTricator at a time, e.g.
  one copy to assemble a program, another copy to play a game meanwhile
  (provided you have enough memory in your QL).
  
  If you have a standard 8 MHz MC68008-based QL, a main disadvantage is
  SPEED! A common property of all emulators known to man is the general
  lack of speed. Since single Z80 instructions are being translated into at
  least six and sometimes as much as tens of MC68000 instuctions, XTricator
  is bound to be slow. Luckily, the ZX81 usually runs in SLOW mode, in
  which a giant portion of CPU time (about 75%) is consumed by the
  screen-interrupt, making the Z80 run effectively about four times slower.
  Thanks to this SLOW mode, XTricator is capable of performing at about 30%
  of the ZX81 in SLOW mode. Obviously, in FAST mode (which neglects
  interrupts), this decreases to one fourth, i.e. 8% (XTricator has no real
  FAST mode; QL I/O and interrupts are not that expensive on processor
  overheads). Although 30% may seem terribly slow, this speed is sufficient
  for running most (machine code) games and utilities. In fact, the ZX81 is
  quite a fast computer and nearly all machine-code games use fixed
  delay-loops for proper human operation. Taking out these delay loops (or
  even better: making them processor speed independent) will make most
  games as fast and exciting as they were on the ZX81. Experimenting a
  little, I found that professional machine-code utilities (like TFO
  DataBase, Artic Assembler, Campbell DisAssembler and Coral Basic
  Interpreter) hardly suffer from the decrease of speed, since most of the
  time you are either typing something or reading output produced by the
  programs. Additionally, BASIC programs can be compiled with an existing
  ZX81 compiler (e.g. MCODER-2), often resulting in a giant speed gain.
  
  If you are so lucky to own a (Super) Gold Card, speed is no longer a
  problem and XTricator becomes more interesting. The emulator then runs at
  a speed of a least 100% of the original ZX81. The same should apply if
  you own a QL Emulator for the Atari ST.
  
  Top performance is obtained on the QXL-card for PCs and similar
  68040-based QL systems. A speed up to four times normal ZX81 speed is
  feasible. Since this is way too fast for most ZX81 programs to be used by
  human beings, the emulator can easily be slowed down to more acceptable
  speeds!
  
  
  WARRANTY
  
  If you come across a ZX81 program which doesn't work on XTricator and
  also doesn't fall in any of the "incompatibility catagories" discussed in
  this manual, please send me a copy of the program on a 3.5" floppy. If
  XTricator is to blame, you will receive a new (repaired!) version of
  XTricator for free.
  
  
  ABOUT THE AUTHOR
  
  I was born in 1967 and bought my first computer (guess what, it was a
  ZX81!) in 1982. With no prior programming experience at all, I started
  writing simple Basic programs. After about one year, it appeared to me
  that Basic just couldn't solve the problems I devised. So, I turned to
  Z80 machine code (with obliging help of Toni Baker; that is, of her
  book). A whole new world of possibilities opened up before my very eyes.
  High-speed compact code and access to all system utilities at lowest
  level, what else does a programmer need? Many Z80 programs were born, and
  some of them were even published in international magazines. In 1987, I
  decided to buy a QL (during sales) and found this younger brother
  (sister?) just as interesting as the ZX81. It also gave me a good excuse
  for learning MC68000 machine code. As I saw that less and less people
  were actually using the ZX81, I sought a way for elongating its
  existence. I thought that (amongst other things) a ZX81 emulator for the
  QL would be a good way to do so, and I started writing this program in
  the end of 1989. By now, in 1994, you can judge the result of my efforts.
  I sincerely hope that many (former) ZX81 users will take some time to
  leap back in history and (re)enjoy the overwhelming simplicity of the
  64k, 8-bit, 3.2 MHz Z80, black & white computer with 64x44 graphics
  resolution, which introduced over a million people worldwide (including
  myself) to the wonderful world of computing. My present-day occupation as
  doctor of physics offers me the opportunity to work with the latest
  technology in computers, but at home I still prefer to use those
  absorbing machines made by Sinclair...
  
  
  ZX81 MAGAZINES
  
  All 'leading' computer magazines have left the ZX81 users in the lurch.
  Fortunately, there still are smaller magazines that are solely dedicated
  to the ZX81. At this moment, I know of the existence of two active ZX81
  magazines, but if you know of any other ones, please send me details, and
  I will be happy to include them in the list below!
  
  In English:      ZX-91: (I'm not quite sure if it still exists...)
                   Andre Baune, 304 Scott, Chateauguay, Quebec, 
                   Canada J6J 4H5.
  
  In German:       ZX-Team Magazin: (excellent!)
                   Joachim Merkl, Bernbacher Strasse 12, D-90768 Fuerth,
                   Germany.
  
  These magazines are basically for free: you only pay for reproduction
  costs and postage. If you write to any one of the editors, include at
  least one IRC for their reply. And do me a favour, will you? Please
  mention where you got the information about the magazines from!
  
  
  XTRICATOR OFFICIAL RELEASE HISTORY
  
  This section has been moved to a separate file: 'Updates_txt'
  
  
  FINAL NOTES
  
  All rights of XTricator and this manual reserved by law (copyright);
  Consequently: UNAUTHORIZED copying, hiring and lending prohibited (please
  refer to section "Registration" for more details). Speed tests performed
  on a regular 8 MHz MC68008 QL with 896k Trump Card, on a QL fitted with a
  16 MHz Gold Card, and on a QXL, in all cases XTricator running as
  single-tasking job at default priority. Just to keep the lawyers happy:
  ZX, ZX81, QL and QDOS are registered trademarks of Sinclair Research
  Limited. The (Super) Gold Card and QXL are available from Miracle Systems
  Ltd, York, U.K. Special thanks to Martin van der Zwan for thorough
  testing and a lot of useful ideas! For more information on XTricator, QZ,
  Coral Basic Interpreter or any other subject related to the ZX81, please
  contact me at:
  
                   Dr. Carlo Delhez,
                   Emmastraat 3,
                   4651 BV Steenbergen,
                   Netherlands.
  
  
  Thanx 4 reading the manual & 4 using XTricator !!
  
  
  -------------------------------------------------------------------------
  
  ****** SHAREWARE RELEASES from the same author: *************************
  
  >>>>>> SPECTATOR,
         ^^^^^^^^^^ a ZX SPECTRUM emulator for the QL; requires 16 MHz Gold
         Card or QXL for reasonable operation speed (35% and 120%). Send
         four (4) QDOS-formatted brand disks (DS/DD 3.5") to me for a
         non-registered test version (two disks are to cover my P&P). Or
         register immediately for only NLG 60 (method of payment: same as
         described in section 'Registration' of this manual).
  
  >>>>>> XTENDER,
         ^^^^^^^^ a ZX81 emulator for PC/XT/AT/386/486 MS-DOS machines, any
         video card; benchmark: from 35% on an original 4.75 MHz 8088 PC up
         to 800% on a 33 MHz 80386dx machine, and beyond... Send two (2)
         MS-DOS-formatted brand disks (DS/DD or DS/HD 3.5") to me for a
         non-registered test version (one disk to cover my P&P). Or
         register immediately for only NLG 60 (method of payment: same as
         described in section 'Registration' of this manual).
  
  >>>>>> UNGIF/ENGIF,
         ^^^^^^^^^^^^ fast and compact utilities to view and generate
         GIF-files on Qdos-based systems. GIF = Graphics Interchange
         Format, a machine-independent graphics file-format. Thousands of
         beautiful full-colour photographs and drawings can now be viewed
         on your QL, and you can port your own QL graphics to other
         machines (e.g. MS/DOS or Unix) without any problem.
  
  -------------------------------------------------------------------------
  End of file
  
