
-------------------------------------------------------------------------------

      ****   XTENDER ZX81 EMULATOR -- Preliminary Version 0.64   ****

                      by Carlo Delhez, June 1992

-------------------------------------------------------------------------------
 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 16 pages @ 60 lines/page).
-------------------------------------------------------------------------------

NOTE:   This program is still in a stage of development. Please keep
        this in mind when reading the manual and running the program.
        If you are interested, look out for improved future versions!
        All remarks and suggestions regarding XTender are welcome.


CONTENTS

- Introduction - Program Description - Registration - Compatibility -
- Comparison - Starting XTender - Commandline Qualifiers -
- Keyboard Facilities - Keyboard Compatibility - Keyboard Lock -
- File Management - Printer Output - High Resolution - ZX81 64k Memory Map -
- ROM and 8-16k Area - Stopping - Clock Frequency - Speeding Up -
- Slowing Down - Z80 Emulation - Writing Programs - Program Transportation -
- Screen Saver - Other ZX81 Emulators - Warranty - About the Author -
- XTender Release History & Future - Final Notes -


INTRODUCTION

The ZX81 is the second computer marketed by Sir Clive Sinclair in the early
eighties. In 1980, he introduced his first computer and called it 'ZX80'. In
those days, computers were far from the 'common good' they are nowadays and
the ZX80 was a relatively cheap machine. It was offered for around 100
pounds (and was marketed as 'the worlds first complete personal computer for
under 100 pounds'), while its closest competitor (the VIC20 from Commodore)
was about three times as expensive. Although the ZX80 was quite a success
(50,000 sold), it had some shortcomings, e.g. it could only do integer
calculations (no floating point), the screen flashed at every keypress and
went blank during execution of programs (this did increase speed but was not
very 'ergonomic'). An upgraded version of the ZX80 appeared within a year.
It had an 8k ROM (instead of the 4k of the ZX80), could do floating point
mathematics and offered a choice between FAST operation with black screen
(as on the ZX80) or SLOWer operation with normal screen. This updated version
was called ZX81. It had a Z80A processor operating at 3.2 MHz, 1k RAM (yes!
only 1024 bytes, but expandable to 48k), 32x24 text screen and 64x48 graphics
resolution in black and white. Programs could be stored on tape and be
retrieved at 300 baud. The first versions sold for 70 pounds (ready built) and
50 pounds (DIY kit); 50,000 ZX81's were purchased in the first 3 months after
its release. Later computers from Sinclair include the ZX Spectrum (1982, Z80
based, 3.5 MHz, 16k ROM, 48k RAM, colour, sound, high resolution, a lot faster
thanks to screen-hardware instead of -software, ASCII based character set and
more expansion possibilities) and the QL (Quantum Leap, 1984, 68008 based,
8 MHz, 48k ROM, 128k RAM [upgradable to 68000, 24 MHz, 2M RAM], multitasking
and !superb! operating system QDOS). Although the Spectrum was undoubtedly the
most popular of all Sinclair machines, I think that many people using MS/DOS
machines nowadays may have been introduced to the world of computers by way of
their (late) ZX81. I hope these people will re-enjoy working with this simple
yet very fine computer again. Run XTender and be my guest!


PROGRAM DESCRIPTION

XTender is - stated very accurately - a Z80 Emulator in a Sinclair ZX81
environment, written for MS/DOS compatible machines with a standard graphics
adapter (Hercules, CGA, PCjr, EGA, MCGA or VGA). The Z80 Emulator is able to
execute programs written in the Z80 machine code language. The ZX81
environment includes the original ZX81 ROM and additionally caters for
`hardware compatibility' (such as keyboard reading, screen output control
and redirecting of signals originally heading for devices such as tape and
lineprinter). The Z80 Emulator and the ZX81 environment are joined in a single
block of 8086 machine code, which - as a whole - shall be referred to as ZX81
Emulator, and is named XTender.

NOTE:  XTender contains the original ZX81 ROM code. This code is copyright
       software. Therefore, XTender may ONLY be used by you if you own a
       ZX81 YOURSELF. In that case, you are IN PRINCIPLE able to LEGALLY
       transport the ROM code from your ZX81 to your PC.
       Any usage of XTender by people NOT owning a ZX81 is in conflict
       with copyright laws.


REGISTRATION

XTender is distributed as ShareWare. You are allowed to make copies for
other people, provided you copy ALL the files and do NOT make changes in
any one of these files. Test XTender during a trial period of 21 days and
then delete the files if you don't like to use the program.

However, if you DO like to use XTender, 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.
Additionally, you will receive LOADS of ZX81 software on MS/DOS disks.
Over 200 programs are already available and the library is still growing!
Interested in all those action games, utilities, educational programs,
hi-resolution software and even scientific applications? Then: REGISTER NOW!
Registration also includes conversion of your own ZX81 programs from tape to
disk, free technical support by the author and the possibility to obtain a
custom-made version of XTender to suit your specific hardware configuration.

To become a registered XTender user, send a cheque or money order worth
Hfl 50 (Dutch Guilders) made payable to J.L. Delhez, plus a note stating your
name, address and the version number of this copy of XTender to me (address at
the bottom of this document). The most recent version of XTender, the first
disk of the ZX81 program library (both on 3.5" DS/DD 3M floppies) and a
laserprinted copy of the manual will be dispatched you (sorry, no 5.25" disks).
If you wish, you can also send banknotes instead of a cheque. Please do not
send cheques in a currency other than Dutch Guilders.


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 PC 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 and Hi-Res, although the characterset can be redefined
in the usual way) are NOT (yet) supported by XTender.

Apart from these exceptional applications, ANY program running on the ZX81
should ALSO run on XTender.


COMPARISON

To name just a few advantages of XTender with respect to the ZX81: safe housing
in a well-stabilized computer (none of the tricky business with wobbling RAM
packs), full 64k RAM available (including POKEable ROM and 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, a SuperBreak facility, reset under keyboard control, etc.

A disadvantage may be operation speed. On slow machines, the processor
emulation might become quite dull. On fast machines, the speed becomes far too
high for reasonable operation. Therefore, TWO versions of XTender are supplied:
a speed optimized version for slow machines and a (slower) user-variable-speed
version for fast machines. More about this in the section `Slowing Down.'


STARTING XTENDER

For running XTender, you need an MS/DOS machine with a standard graphics
adapter (Hercules, CGA, PCjr, EGA, MCGA or VGA) and about 128k of free memory
to store the program and the required work space. Note that you need MS/DOS
version 2.0 or higher (or compatible). XTender refuses to start with lower
version numbers. XTender is designed to be compatible with all processors from
8088 up to 80586, including the NEC's.

As said earlier, the disk contains two versions of XTender. These are called
XTENDERF.COM and XTENDERS.COM. The first is the fastest version and should be
used on slow machines. The second one is not speed-optimized, hence slower.
However, this one has the possibility to slow emulation down considerably and
should be used on (very) fast machines. The user must determine by experience
which one works best on his machine. A rule of thumb:

          XTenderF is 50% faster than the fastest setting of XTenderS
       or
          the fastest setting of XTenderS is 30% slower than XTenderF

To start the program, simply type

          XTENDERF      (fast version)
       or
          XTENDERS      (slow version)

(whichever you prefer) at the DOS prompt. This will start XTender. You will
hear a small beep and next, depending on the speed of your computer, you will
see some flashes and/or weird characters while the ZX81 performs a reset, but
eventually the famous inverse-K-cursor should appear and XTender is ready
for use.

Xtender tries to determine what video card you have installed simply by looking
at the current video mode in order to make a destinction between Hercules and
non-Hercules. In Hercules, only a small portion of the display will be used,
in all other cases, the ZX81 screen occupies almost the entire display. If you
have CGA emulation on your Hercules card and want to use it with XTender, make
sure you do NOT start XTender with video mode 7 (you can see this, for example,
with Norton SysInfo). Similarly, if you DON'T have Hercules, make sure you
DON'T start XTender with video mode 7.


COMMANDLINE QUALIFIERS

Instead of starting XTender as described in the previous section, you can
also add qualifiers to the command in to order to influence the emulator's
behaviour. Qualifiers are single-letter switch parameters preceeded by
a forward slash '/', minus sign '-' or plus sign '+'. The qualifiers currently
available are:

/?      display help screen with a list of all qualifiers.

/c      force CGA screen mode; use this qualifier when XTender tries to use
        Hercules although you have a CGA (or higher) video card installed;
        this option may also be chosen when your video card can handle both
        CGA and Hercules, and you specifically want the CGA mode.

/d:nnn  set emulator delay factor; `nnn' is a decimal number in the range
        0 through 128; this qualifier is equivalent to the ZX81 command
        `POKE 23,nnn' after XTenderS has been started; for more information,
        see section `Slowing Down'.

/e      force Hercules screen mode; use this qualifier when XTender tries to
        use CGA although you have a Hercules video card installed; this option
        may also be chosen when your video card can handle both CGA and
        Hercules, and you specifically want the Hercules mode.

/h      display help screen with a list of all qualifiers.

/i      force inverse video, i.e. white characters on black background, which
        seems more comfortable for the eyes in case of serious applications.
        Note that CTRL-F2 can be used to toggle screen colour once the emulator
        is started (see section 'Keyboard Compatibility').

/m      skip ZX81 memory test; after a NEW or Reset, the ZX81 ROM performs
        two main actions: it tests the RAM memory and sets up the display
        file. Each of these takes about half the reset-time. On an emulator,
        the memory test is rather superfluous and can be omitted by this
        qualifier, thus reducing the reset-time by at least 50%. Note that
        the RAM memory is still cleared (zero-filled).

/v:nnn  select high byte of paragraph of start of video memory; this option
        should be used with great care and only when neither the /c nor the /e
        qualifier produces proper screen output. Random experiments with the
        value of nnn will cause a system crash.

Upper- and lower-case letters are freely interchangable. Spaces inbetween
successive qualifiers are optional. When the /? or /h qualifier is present,
only the help screen will be displayed and XTender isn't actually started.
Commands are interpreted left-to-right: later settings supersede earlier
settings.

When no qualifiers are given, XTender is started with the following default
settings:

        IF video_mode=7 THEN
          XTENDERS /d:0 /e /v:176
        ELSE
          XTENDERS /c /d:0 /v:184
        END IF

(and the same for XTENDERF), i.e. no delay factor, normal video and the
regular video memory paragraphs (B000h and B800h, respectively). Any qualifier
given by the user supersedes these default settings.


KEYBOARD FACILTITIES

A problem for many users may be the keyboard: the ZX81 works with tokens and
single keypress entries (e.g. pressing just `P' gives the token `PRINT').
XTender solves this problem by providing a graphical help screen. Just press
CTRL-F1 and the keyboard help screen will pop up. Press any key to return
to the ZX81 screen. The help screen is a scanned copy 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 (abbreviated ASN)
                  - a gray block

Pressing the A-key will produce 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 (or keypad `5') and Shift-9, respectively.

The default ZX81 screen color is black characters on white background (unless
you have used the /i qualifier). For games with a lot of graphics this may be
nice, but for text handling, I find the inverse more comfortable for the eyes.
Press CTRL-F2 to change the display from black on white to white on black and
vice versa.

Some ZX81 (machine coded) programs do not allow you to stop them using
Break (Space). On XTender, programs can always be stopped using CTRL-ESC.
This will actually cause a jump to an address in ROM where a RST 8 for error D
is located, and hence the stack is cleared, the error message is displayed and
you are back in Basic. Some programs crash the ZX81 if you try this, as they
may have messed around with the system variables, Basic area, screen or even
with the ROM code. If CTRL-ESC causes a ZX81 `hangup', press CTRL-ALT-ESC. This
restores the original ROM code and subsequently executes a RST 0. ANY program
can safely be aborted using CTRL-ALT-ESC. Note that the PEEK values of
address 23 is preserved (or should be!).

In general, CTRL-ESC should only be used when the normal Break is disabled.
If you use CTRL-ESC in the normal ZX81 editor, it will lock keyboard
operation. Press CTRL-ESC once more to get proper key response again.
In the CBI editor, CTRL-ESC merely produces a space character, i.e. does
not lock the keyboard. In all cases, avoid using CTRL-ESC when CBI Trace is
active.

All the legal CTRL keypresses generate a modest beep when they are recognized
by XTender; you can then release the key(s) and await the desired result.
CTRL together with a key other than one of the above has the effect of SHIFT
pressed together with that key. Finally, CTRL-C and CTRL-Break are hooked and
have no drastic effect (CTRL-C produces Shift-C, i.e. a question mark).


KEYBOARD COMPATIBILITY

The ZX81 keyboard is totally different from the PC XT/AT keyboard. First
of all, the ZX81 has only 40 keys. These are arranged according to the
familiar QWERTY layout, yet - as you can imagine - 26 letter keys, 10
number keys, Shift, Space and NewLine (the ZX81 equivalent of Enter) already
make a grand total of 39 keys. The remaining 40th key is a full stop (`.').
So: all other symbols are hidden as Shifted keys and (to make things more
complex) in a non-PC-like fashion. The ZX81 works in UPPER CASE only, so in
fact you have 39 Shift options (barring Shift itself, all keys can be Shifted,
including Space and NewLine). Symbols are really scattered around the keyboard
(can you imagine using Shift-`B' for `*' and Shift-`U' for `$' !?!) and you
will really need the CTRL-F1 help facility (or your own ZX81 manual) and some
patience for locating the symbols.

For UNSHIFTED keys, XTender maps almost the entire PC keyboard onto the ZX81
keyboard. Not only the 40 basic ZX81 keys, but also things like the Cursor
Keys, BackSpace and the Numeric Pad are mapped. For example, if you press
`Cursor Left', XTender will convert this to Shift-`5', the ZX81 equivalent.
This makes editting (and sometimes also playing games) less strenuous. The
central key of the numeric pad (`5') generates Shift-Enter, i.e. toggles
Function mode (a special cursor mode for obtaining functions tokens). More
special keys: the square brackets (`[..]') become normal brackets (`(..)') and
the single forward quote gives the standard ZX81 double quote. The ESC key
generates Shift-1 (Edit), i.e. brings the current cursored BASIC line in the
editor.

Also for SHIFTED keys, the emulator helps you a little bit. Pressing any one
of the Shift keys will always give you the ZX81-Shifted symbol (like Shift-`U'
for `$'). BUT, if you press ALT instead of SHIFT, you will get the PC-Shifted
symbol, so you can press Alt-`4' to get the $tring sign. Some non-trivial
ALTernatives are listed below:

            ALT-`6' gives `**'   (instead of `^')
            ALT-`7' gives `AND'  (instead of `&')
            ALT-`[' gives `<='   (instead of `{')
            ALT-`]' gives `>='   (instead of `}')
            ALT-`'' gives `""'   (instead of `"')

Note again, how the single forward quote (`'') is converted to a ZX81 double
quote (`"') whereas the PC double quote is converted to a ZX81 quadruple quote
(`""'). XTender effectively doubles quotes.

Finally, if CAPSLOCK is ON, the effect of Shift is INVERTED for ALL keys (not
only the letter keys). So, pressing for example `B' with CAPSLOCK ON gives `*',
and Shift-`B' gives `B'. Note that this can be nice for some games which use
the keys 5 through 8 for steering and do not allow you to press Shift (so you
cannot use the PC cursor keys). With CAPSLOCK ON you CAN use the arrow keys of
the keyboard!


KEYBOARD LOCK

When you are a fast typist, the ZX81 may not always be able to keep track
of your typing. In some cases, the PC keyboard seems locked altogether and
the ZX81 does not respond anymore to the characters you are typing. Just hit
CTRL-ESC once to cure this.


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, 6000 baud (20 seconds for 16k).
This was quite acceptable and a single tape of 60 minutes could contain
up to 2.5 M information. However, 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 a more modern Sinclair computer
(the QL) which offers more advanced storage possibilities (diskdrives) and
which is very well suited to act as a fileserver thanks to its multitasking
capabilities (68000 processor). 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 later served as an example for the Disk Operating System offered by my
ZX81 emulator for the QL, "XTricator".

Also in XTender, programs can be SAVEd and LOADed in a format which is
directly compatible to QZ. To SAVE or LOAD a program, just type

          SAVE "<name>"
          LOAD "<name>"

which are the equivalents of the original QZ commands

          SAVE:P:<name>:
          LOAD:P:<name>:

The files are SAVEd to and LOADed from the default drive and path (these
can be changed with the QZ commands USE: and CD:). The SAVEd programs appear
as `.P' files on the default drive/path (`P' stands for Program; other
filetypes, available in future versions, are Basic, Code, Lines, Screen and
Variables).

LOADing a non-existing program will display the proper DOS error. If you
SAVE a program which already existed, it will simply be overwritten without
any user confirmation. Saving a file with a NAME of length zero results in the
usual error F. Originally, QZ filenames were at most 12 characters long. On
the PC, one is so unfortunate to be restricted to 8. So: only the first 8
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.

Other QZ file commands can be passed to XTender in a SAVE or LOAD statement.
The first character must be an asterisk (`*') to indicate that one or more
commands follow (instead of a filename). The available commands, a short
description and examples of each command are listed below:

*BACK:          - Step one level back in current directorypath; in fact equal
                  to CD:..: but included for compatibility reasons.
                - Example: LOAD "*BACK:"

*CD:            - Change current directory to indicated pathname; note that
                  the pathname ends with ':' (as in all other QZ commands),
                  so you cannot use CD: to change the directory on a non-
                  default drive; apply the command USE: instead. The usual
                  MS/DOS backslashes must be replaced by forward slashes.
                - Examples: LOAD "*CD:GAMES:"
                            LOAD "*CD:/ZX81/ASM/TOOLS:"
                            LOAD "*CD:..:"
                            LOAD "*CD:/:"

*DEL:           - Deletes indicated file; the extension of the filename (i.e.
                  the filetype) must be typed first, followed by a colon (':')
                  and the main part of the name; the command is ended by a
                  colon as well. The filetypes recognized by XTender are B, C,
                  L, P, S and V. Note that only files in the current drive and
                  path can be deleted. For deleting files on other drives or
                  paths, use CD: and USE: first. DEL: is the same as REMOVE:.
                - Example: LOAD "*DEL:P:RUBBISH:"  (deletes RUBBISH.P)

*DIR:           - Shows the ZX81 files on the current drive; all the specific
                  ZX81 files (with extensions .B, .C, .L, .P, .S or .V)
                  are listed, together with their length, date and time; note
                  that the date is shown in the format "yy-mm-dd", not in the
                  usual DOS form "mm-dd-yy"; the time is shown in 24-hour
                  format. Subdirectories without extension are also shown.
                  At the end of each page, press any key to see the next page
                  or Q to stop the directory listing; at the top of each page
                  you will see the current drive and pathname; the backslashes
                  are replaced by forward slashes; at the end of the file list
                  you will see the total number of files and the number of
                  clusters left on the current device (depending on your
                  drive's FAT, a cluster can hold 512 bytes, 1k, 2k, 4k etc.).
                - Example: LOAD "*DIR:"

*KILL-XTR:      - Stops the current XTender session, returns to DOS.
                - Example: LOAD "*KILL-XTR:"

*LOAD:          - Loads one of the special filetypes (not P-files!). The
                  filetypes currently available are:
                  * Screen 'S'
                     - the screen file is loaded from disk into the current
                       ZX81 display file. It is assumed that the display
                       file is fully expanded; otherwise: ZX81 crash!
                     - example: LOAD "*LOAD:S:PICTURE:"

*MAIN:          - Go to root directory of current drive; in fact equal to
                  CD:/: but included for compatibility reasons.
                - Example: LOAD "*MAIN:"

*MD:            - Makes new directory as indicated by pathname; note that
                  the pathname ends with ':' (as in all other QZ commands),
                  so you cannot use MD: to create a directory on a non-
                  default drive; apply the command USE: instead. The usual
                  MS/DOS backslashes must be replaced by forward slashes.
                - Examples: LOAD "*MD:JUNK:"
                            LOAD "*MD:/ZX81/GAMES/SHOOT:"
                            LOAD "*MD:../LEVEL2:"

*RD:            - Removes directory as indicated by pathname; note that
                  the pathname ends with ':' (as in all other QZ commands),
                  so you cannot use RD: to remove a directory on a non-
                  default drive; apply the command USE: instead. The usual
                  MS/DOS backslashes must be replaced by forward slashes.
                - Examples: LOAD "*RD:OLD-DATA:"
                            LOAD "*RD:/ZX81/TAPE:"
                            LOAD "*RD:../BACKUP:"

*REMOVE:        - Removes indicated file; the extension of the filename (i.e.
                  the filetype) must be typed first, followed by a colon (':')
                  and the main part of the name; the command is ended by a
                  colon as well. The filetypes recognized by XTender are B, C,
                  L, P, S and V. Note that only files in the current drive and
                  path can be deleted. For deleting files on other drives or
                  paths, use CD: and USE: first. REMOVE: is the same as DEL:.
                - Example: LOAD "*REMOVE:C:ZXASSEM2:"  (removes ZXASSEM2.C)

*ROOT:          - Go to root directory of current drive; in fact equal to
                  CD:/: but included for compatibility reasons.
                - Example: LOAD "*ROOT:"

*SAVE:          - Creates one of the special filetypes (not P-files!). The
                  filetypes currently available are:
                  * Screen 'S'
                     - the current ZX81 display file is written to disk. It is
                       assumed that the display file is fully expanded; this
                       means that the resulting S-file is always 793 bytes
                       in length (namely 24*33+1).
                     - example: LOAD "*SAVE:S:DISPLAY:"

*SHOW:          - Shows information about the current version of XTender plus
                  a list of all QZ commands available.
                - Example: LOAD "*SHOW:"

*USE:           - Selects another drive as default drive. If you have only one
                  physical floppy drive, which can be accessed logically as A:
                  or B:, Xtender will always use the last logical setting of
                  this drive to avoid the DOS message requesting to insert a
                  disk (very few other programs I know also do this!). But note
                  that this only works from DOS 3.2 onwards.
                  A pathname cannot be included, use CD: instead.
                - Example: LOAD "*USE:D:"  (selects drive D:)

Please note the colon (`:') at the end of each command, acting as a separator.
More than one command can be given in a single LOAD or SAVE by separating
successive commands with a semi-colon (`;'). Only one asterisk is needed,
e.g. LOAD "*USE:B:;CD:../GAMES:;DIR:"

Any non-supported command after the `*' will display the erroneous text plus
the message `ERROR IN QZ COMMAND', and stops with Error C (syntax error).


PRINTER OUTPUT

No printer driver is available as yet. This will be implemented in future
versions.


HIGH RESOLUTION

Sir Clive Sinclair himself said that it could not be done. Still, 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 real 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.

Hi-Res is detected by XTender by trapping an immediate change in value of
register IX (used by the ZX81 as NMI server address). The term `immediate'
means that only the instruction `LD IX,nn' (DDh.21h) is trapped. You could
avoid the trap by using a sequence like `LD HL,nn \ PUSH HL \ POP IX'.
However, all Hi-Res programmes tested use the (more obvious) immediate method.

After the detection, XTender first tries to emulate the Semi Hi-Res by
looking for the chacteristically shaped 6k display file in the bottom 16k of
RAM and printing it to the PC screen appropriately. If it cannot locate this
display file, normal resolution will be switched on.

As fas as I know, only HRWP (Hi-Res Word Processor) does not function properly
on XTender, but I'm working on that!


ZX81 64K MEMORY MAP

begin_address   end_address     description

 0000h     -     1FFFh          original ZX81 8k-ROM area.
 2000h     -     3FFFh          8-16k area; on the ZX81 this area can only be
                                used when additional hardware is fitted (e.g.
                                64k RAM pack or EPROM card); the standard ZX81
                                shadows its ROM in this area.
 4000h     -     FFFFh          48k of RAM; at startup, the ZX81 allocates
                                at most 16k of RAM to BASIC; the remaining
                                32k is kept free for data storage; more area
                                can be allocated to BASIC by moving RAMtop
                                (system variable at 4004h) upwards.

 4000h     -     407Ch          system variables
 407Dh     -    [400Ch]-1       BASIC program area
[400Ch]    -    [4010h]-1       display file (text mode!)
[4010h]    -    [4014h]-1       BASIC variables area
[4014h]    -    [401Ch]-1       work space
[401Ch]    -    [4004h]-1       free memory available for BASIC; this area is
                                cleared by NEW; the machine code stack grows
                                down from the top address of this area
[4004h]    -     FFFFh          free memory that cannot be used by BASIC and
                                that is also not influenced by NEW, useful for
                                resident utilities or RAMdisk; provided [4004h]
                                is above 7FFFh, this area is also not altered
                                by RST 0.

Note: [addr] is the value obtained by PEEK(addr)+256*PEEK(addr+1), i.e. the
usual Z80 double-peek with the low byte before the high byte.


ROM AND 8-16K AREA

On XTender, the ROM and 8-16k area are in fact also part of RAM, i.e. they are
not POKE-protected. This can be nice for making slight changes in the ZX81 ROM
or for using the 8-16k area for machine code utilities that can be loaded from
disk.

At startup, the 8-16k area contains a version of ZX-ASSEMBLER-2, a revised
version of this well known Artic program. In a future version of XTender, this
will be replaced by CORAL BASIC INTERPRETER (CBI version 7.0). The Assembler
is started by typing:

        RAND USR 8192

No further comments on the use of the Assembler are given here. For those
familiar with the Assembler, it must be noted that an ORG directive is now
available (the code is still generated in line 1, but can easily be moved to
the proper place by accepting the default values of the Copy option).


STOPPING

There are two ways to end your XTender session. First, the QZ command KILL-XTR
can be typed in a SAVE or LOAD statement, e.g.:

        LOAD "*KILL-XTR:"

which will bring you back to DOS. As this requires quite a lot of typing, you
can also use the quicker alternative

        LOAD " STOP "

with STOP typed as a keyword (i.e. Shift-A instead of the separate letters)!
This will bring you back to DOS as well.


CLOCK FREQUENCY

The effective clock frequency can be determined in several 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 XTender 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 XTender takes half the time the ZX81 would take to execute it
in SLOW, the effective clock frequency is (0.8 MHz)/(0.5) = 1.6 MHz.

Another way to find the clock frequency is to use a machinecode 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.

A very good estimate of the emulated processor speed can be obtained by
LOADing the program CLCKFREQ. This program does some simple printing and
plotting, but the final result is a reliable measure for the average speed
of XTender and the effective (emulated) processor speed.


SPEEDING UP

XTender versions 0.00 thru 0.23 had a speeding-up routine which allowed for
an increase of speed by reducing the screen output frequency. On more recent
versions (like this one) the screen routine has been completely revised and on
all machines a screen output frequency of 18.2 Hz is used without loss of
emulation speed (actually, on some machines XTender will even runner quicker!)
Consequently, POKEing address 37 has no sensible effect anymore.


SLOWING DOWN

On fast machines the speed of the emulator (XTENDERS only!) can be reduced by
POKEing address 23. The byte at this address is used as delay counter at each
Z80 instruction. Default value is 0, which gives (practically) no delay. A
higher value will quickly slow emulation down. The maximum value you may use
is 128, which results in a factor 27 slowdown (i.e. 27 times slower than with
value 0 poked); if your computer is so fast that even this is not sufficient,
please write me to obtain an even slower version. Poking the values 129
through 255 responds just as poking 0, i.e. no delay.

Example of SLOWDOWN on a 33 MHz 80386dx machine:

version         PEEK 23         Speed           Z80 Frequency

XTenderF         --             925%            7.5  MHz
XTenderS          0             625%            5.0  MHz
XTenderS          1             525%            4.2  MHz
XTenderS          2             450%            3.6  MHz
XTenderS          4             355%            2.8  MHz
XTenderS          8             250%            2.0  MHz
XTenderS         16             155%            1.2  MHz
XTenderS         32              88%            0.71 MHz
XTenderS        128              23%            0.18 MHz

Please note again that the slowing down does NOT work with XTENDERF.
Once you have determined which value of PEEK 23 suits your needs best,
you can start XTenderS with the /d:nnn qualifier in order to set the delay
factor to `nnn' without actually having to poke it into the ZX81 memory.
Ofcourse, you can still alter this initial value during the session!


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 XTender to function, the
latter statement must be true. Also, many ZX81 programs have been
tested on XTender 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 Subtract flag of the Z80 flag-register (f) is NOT emulated. Many Z80
  instructions alter this flag, but there is only one instruction which uses
  the result, viz. DAA. Since DAA is used only once in the ZX81 ROM (where it
  has been replaced by an equivalent non-standard Z80 instruction) and since
  proper emulation of the Subtract Flag reduces operation speed of XTender, I
  think this exclusion is a sensible decision. Note that, when XTender
  encounters a DAA instruction, it performs a `Decimal Adjust After Addition'.
  So, keep your fingers crossed!

  Programs using DAA :   --- Reversi (only the machine coded version)
                         --- MCTT (Machine Code Testing Tool)
                         --- Frogger

  If you should know of other programs which use DAA, please tell me!

* The IN instructions are all neglected, except for requests for port $FE,
  (the keyboard) and port $FB (the printer). Also, OUT instructions are
  neglected. Note, however, that the instructions IND, INDR, INI, INIR, OUTD,
  OTDR, OUTI and OTIR alter the registers BC and HL (and also (HL)'s)
  appropriately!

* HALT waits for an interrupt. Interrupts are not emulated and therefore
  HALT is made equal to NOP.

* Some instructions cannot be used for changing the ROM area (0-8k). These are:

        LD (HL),A       LD (DE),A
        LD (HL),D       LD (HL),E
        LDIR

  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, XTender (which has no write-protection in the ROM area) would alter
  its own code, which is (in general!) a bad thing. 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...


WRITING PROGRAMS

For the success of XTender and perhaps for a revival of the ZX81, I recommend
authors of new programs (either in machine code or in BASIC) to write their
software such that it will run on both XTender and on the ZX81. As an
example, you could perform nice tricks with XTender by POKEing its ROM, but
that is not possible on the ordinary ZX81, i.e. INCOMPATIBLE! Please avoid such
tricks or - if they are absolutely necessary - clearly include a message
telling on which machine(s) the program runs (ZX81, XTender, XTricator or
the Atari Emulator). I also advise to use processor independent delay loops
where necessary (mostly games and editors). Basically, these look like this:

        REPEAT
          SET CLOCK
          BEGIN
            PERFORM ACTION
          END
          REPEAT
            READ CLOCK
          UNTIL CERTAIN TIMELIMIT EXCEEDED
        FOREVER

Programs written this way are equally fast on every computer (unless the
ACTION part takes more time than given by CERTAIN TIMELIMIT). In fact, several
existing ZX81 programs were really written this way and are consequently
not sped up by a fast emulator (only decelerated by a slow one...)!
For reading and setting the clock, make use of the system variable Frames.
Frames is a two-byte number, decrementing at 50 Hz. Please note that

        (1) Frames is decremented in SLOW mode ONLY on the ZX81;
        (2) Frames is decremented in FAST AND SLOW mode on XTender;

Also in BASIC programs, use the value of Frames (e.g. by way of PAUSE) instead
of some empty FOR-NEXT loop for delays.
Normally, the PC uses an 18.2 Hz interrupt to keep track of the time of day.
XTender reprograms the timer to the 50 Hz rate used by the ZX81, but does
some clever things to make sure that your PC clock doesn't notice this much
higher frequency! Only hi-res programs may slacken your PC clock.
When you return to DOS, the timer frequency is set to 18.2 Hz again.


PROGRAM TRANSPORTATION

Some trouble is caused by the fact that ZX81 programs were usually stored on
tape instead of disk. Please write me for info on conversion!


SCREEN-SAVER

XTender has a built-in screen-saver which will be activated when the ZX81
display remains unchanged AND no key is pressed during 3 minutes. When the
screen saver is active, any keypress (including Shift etc.) will restore
the ZX81 screen. Note that a change of the ZX81 display itself in the saved
state will not restore the ZX81 screen! The screen-saver is always deactivated
in Hi-Res modes.
If you have another screen-saver memory-resident, it may or may not be
superseded by the screen-saver of XTender (depending on how exactly that
screen-saver was coded).


OTHER ZX81 EMULATORS

The PC is not the only computer for which a ZX81 emulator has been written.
An equivalent ZX81 emulator has also been written for the SINCLAIR QL and for
the ATARI ST computers. The emulator for the Sinclair QL is called XTricator
and is written by myself. It is completely compatible to XTender as far
as file formats are concerned. This development of XTricator was started in
1989 and that program offers far more possibilities than XTender (let alone
the multitasking capabilities of the QL!). But, future versions of XTender will
increasingly more resemble XTricator!

I have no personal experience with the emulator written for the Atari, but
it seems that programs running on that emulator can be LOADed directly
into XTender/XTricator and RUN without problems.

Note that the files with extension '81' on the Atari emulator are compatible
to the 'P' files of XTender and XTricator.

It seems that the Atari emulator has problems to LOAD files not SAVEd by
the emulator itself (again, I have no personal experience). As far as I know,
XTender/XTricator 'P' files cannot be converted to Atari '81' files because of
this 'sensitivity'. It is ofcourse the virtue of XTender and XTricator that it
DOES work the other way round!


WARRANTY

If you come across a ZX81 program which doesn't work on XTender 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 XTender
is to blame, you will receive a new (repaired!) version of XTender 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 68000 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. My present-day occupation as an engineer of physics obliged me to
buy an MS/DOS machine. In order to stay loyal to the absorbing machines made
by Sinclair, I decided to write a ZX81 emulator for MS/DOS as well. The
8086-family is very similar to the Z80, so I did not really have to learn a
new language, only a new OS. By now, in 1992, 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...


XTENDER RELEASE HISTORY & FUTURE

Version   Date              Remarks

0.07      October 1991      First documented pre-release

0.62      June 1992         Current version

< 1.00    June-Dec 1992     Illegal preliminary versions, likely to contain
                            undocumented features and bugs. Use at your own
                            risk or write me to become a registered XTender
                            user.

1.00      December 1992     First official release.


FINAL NOTES

All rights of XTender and this manual reserved by law (copyright);
Consequently: UNAUTHORIZED copying, hiring and lending prohibited
(please refer to section "Registration" for more details).
Just to keep the lawyers happy: ZX, ZX81 and QL are registered trademarks of
Sinclair Research Limited.
For more information on XTender, XTricator, QZ, ZX-Assembler-2, Coral Basic
Interpreter or the ZX81 in general, do not hesitate to contact me at subjoined
address in writing:


          Carlo Delhez,
          Emmastraat 3,
          4651 BV Steenbergen,
          Netherlands.

          via E-Mail on Internet:
          tnndcarlo@cycl.phys.tue.nl  (until May 1994)


Thank you for reading the manual & for using XTender !!

------------------------------------------------------------------------------

    PLEASE READ THE FOLLOWING MESSAGE ONCE MORE !!!

    XTender contains the original ZX81 ROM code. This code is copyright
    software. Therefore, XTender may ONLY be used by you if you own a
    ZX81 YOURSELF. In that case, you are IN PRINCIPLE able to LEGALLY
    transport the ROM code from your ZX81 to your PC.
    Any usage of XTender by people NOT owning a ZX81 is in conflict
    with copyright laws.

------------------------------------------------------------------------------

<*** End of File ***>
