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

   ****   XTENDER ZX81 (TS1000) EMULATOR -- Preliminary Version 0.93   ****

                      by Carlo Delhez, January 1993

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

        !!! EXPECTED SOON !!!  ....  ZX81TAPE ....

        A utility to read ORIGINAL ZX81 TAPES directly into your PC,
        immediately suited for loading into XTender.  Only a simple
        DIY interface will be needed. Write me if you're interested!


CONTENTS

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


INTRODUCTION

The Sinclair ZX81 (or Timex/Sinclair TS1000) 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 ZX81s 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.
XTender is written !entirely! in Assembly Language for best performance. The
source comprises over 8,000 lines (with the numerous macros still unexpanded!).


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 on a ShareWare basis. 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 EuroCheque worth NLG 50 (Dutch
Guilders) 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 TWO disks of the ZX81 program library
(all on 3.5" DS/DD 3M-branded floppies) and a laserprinted copy of the manual
will be dispatched you (sorry, no 5.25" disks).

IMPORTANT:
^^^^^^^^^^
   For cheques OTHER THAN EuroCheques, please ADD NLG 20 for additional
   cashing costs. Do NOT send cheques in a currency OTHER THAN Dutch Guilders.
   If you wish, you may also send CASH (banknotes) instead of a cheque. In
   case you send banknotes in a currency OTHER THAN Dutch Guilders, please
   use an acceptable rate of exchange and ADD the equivalent of NLG 10 for
   my exchange costs.


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) 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 80486 (and beyond!), including the NECs.

As said earlier, two versions of XTender exist. 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. First you
will hear a beep and see a title page which displays some general information
about XTender and its usage. In case of registered copies, the name of the
owner also appears on this title page. Now press any key to start the actual
ZX81 emulation. 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. Alternatively, you can force
Hercules or CGA mode by the /e and /c qualifiers, respectively (see below).


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 '+' (there is no effictive
difference between these three characters). The qualifiers currently available
are as follows:

/?      display help screen, briefly summarizing 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, briefly summarizing 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 and the standard video
memory paragraphs (B000h and B800h for Hercules and CGA, respectively).
Any qualifier given by the user supersedes these default settings.


SCREEN OUTPUT

XTender uses a PC timer interrupt to write the ZX81 screen regularly into
the PC video memory. For the obvious reasons of speed, the pixel data is
poked directly into the video RAM (instead of using the !VERY SLOW! PC INT's).
This may not work properly on (very) old PC systems. The screen routine is
differential, i.e. only those parts of the ZX81 screen that have changed
since the last interrupt are updated on the PC screen.

Before XTender starts emulating, it first determines the relative speed of
your computer. It does this by running a `benchmark test' and the resulting
benchmark is used to calculate the rate of screen update. For example, if the
measured benchmark is 1000 (33 MHz 80386dx machine), the screen is updated at
a rate of 100 Hz. Lower/higher benchmarks result in proportionally lower/higher
screen update frequencies. As a result of this method, the performance of
XTender is optimized automatically for ANY machine. I have tested XTender
on an original PC (benchmark 50, screen update at 5 Hz) and the emulator
(fast version) executed at a speed of 35% with respect to the real ZX81!

You can see the measured benchmark and resulting screen update frequency
by loading the program SYSINFO.P directly after having started XTender.
This will provide you with all the information you need.

The timer interrupt of the PC can be set to ONE frequency only. However,
XTender actually needs three distinctively different frequencies:

        - 18.2 Hz to keep your PC's internal clock synchronized
                  (you'd be cross with me if I hadn't done this!);
        - 50.0 Hz to update the ZX81 system variable FRAMES
                  (for processor-speed-independent timing loops);
        - nnnn Hz to update the video RAM (nnnn is an arbitrary number
                  determined by the measured benchmark).

I have applied some clever `state of the art' programming techniques to make
sure that all these frequencies are available from only one timer-interrupt!
When you return to DOS, the timer frequency is set to 18.2 Hz again.


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 touched scanner 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 (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 colour 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 to
recover. 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 value
of address 23 is preserved (or should be!).

On some computers, CTRL-ALT-ESC is already in use for system purposes;
therefore, the keypress CTRL-SHIFT-ESC may be used as an alternative.

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 even more
complicated) 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 Dollar $ign. 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, 6,000 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 supported by XTender 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.

QZ file handling commands can be passed to XTender in a LOAD (or SAVE)
statement. The first character of the SAVE/LOAD name must be an asterisk
(`*') to indicate that one or more QZ commands follow (instead of the usual
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: first. 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 format "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:
                  * Basic 'B'
                     - all the lines of the current Basic program are deleted
                       and the the file is then inserted in the Basic area.
                       The variables area remains unchanged. XTender does
                       not check if there is sufficient memory available
                       to insert the file. If not, a crash will result. If all
                       is OK, error 'I' will be generated (data merged).
                     - example: LOAD "*LOAD:B:SORTING:"
                  * Code 'C'
                     - the code file is loaded from disk to the specified
                       address; XTender tries to load all the bytes from the
                       file but stops after exceeding address 65535
                     - example: LOAD "*LOAD:C:CHARSET:8192:"
                  * Lines 'L'
                     - the lines in the file are merged with the current
                       Basic program. If a line with a certain number already
                       exists in the current program, it will be replaced by
                       the new line with the same number. The variables area
                       remains unchanged. XTender does not check if there is
                       sufficient memory available to insert the lines. If
                       not, a crash will result. If all is OK, error 'I'
                       will be generated (data merged).
                     - example: LOAD "*LOAD:L:PARTLY:"
                  * 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:"
                  * Variables 'V'
                     - the variables area of the ZX81 is cleared, and then
                       the file is inserted in this area. The Basic program
                       remains unchanged. XTender does not check if there is
                       sufficient memory available to insert the file. If not,
                       a crash will result. If all is OK, error 'I' will be
                       generated (data merged).
                     - example: LOAD "*LOAD:V:GRAPHS:"

*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: first. 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: first. 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:ZXASSEM:"  (removes ZXASSEM.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-type files (not P-files!). The
                  filetypes currently available are:
                  * Basic 'B'
                     - all the lines of the current Basic programs are written
                       to disk. System variables, Basic variables and screen
                       are NOT written to disk; a B-file is a compact (hence
                       fast) way for storing short programs on disk.
                     - example: LOAD "*SAVE:B:QUICK:"
                  * Code 'C'
                     - the code block starting at the address determined by the
                       first parameter and with a length determined by the
                       second parameter is written to disk. The length must
                       be larger than 0 and the calculated end address may
                       not exceed address 65535. Please note that the second
                       parameter does NOT represent the end address.
                     - example: LOAD "*SAVE:C:CHARSET:7680:512:"
                       (saves the contents of addresses 7680 through 8191)
                  * Lines 'L'
                     - those lines of the current basic program with a line
                       number lying within the interval determined by the two
                       parameters supplied are written to disk. The first line
                       number must be smaller than or equal to the second line
                       number. The second line number must be smaller than
                       10,000. The two line numbers need not actually exist
                       in the current program. If no lines ly in the specified
                       interval, a file of zero length is produced.
                     - example: LOAD "*SAVE:L:ELEPHANT:1000:2000:"
                       (saves all lines with numbers greater or equal to 1000
                       and less or equal to 2000)
                  * 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:"
                  * Variables 'V'
                     - the current contents of the ZX81 variables area are
                       written to disk (including the delimiting CHR$(80)).
                       Directly after a CLEAR (or similar) command, this area
                       is empty and the file will have length 1.
                     - example: LOAD "*SAVE:V:TAXES:"

*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 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 XTender.
For details on this program, read the textfile supplied with this version of
XTender. Two useful commands to enter when the black cursor appears are

          ERR MSGS ON         (explains error messages)
          NOSTALGIC OFF       (enable 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.


STOPPING

There are three 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.
Finally, for the very impatient: pressing CTRL-Break will end XTender 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.


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 (benchmark 1000):

version         PEEK 23         Speed           Z80 Frequency

XTenderF         --             830%            6.6  MHz
XTenderS          0             560%            4.4  MHz
XTenderS          1             460%            3.7  MHz
XTenderS          2             400%            3.2  MHz
XTenderS          4             310%            2.5  MHz
XTenderS          8             220%            1.8  MHz
XTenderS         16             140%            1.1  MHz
XTenderS         32              77%            0.62 MHz
XTenderS         64              42%            0.33 MHz
XTenderS        128              22%            0.17 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:

* 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.

* The Subtract (N) 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 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...


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 ZX81 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.


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!
(Also see top of this document)


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. The development of XTricator was already started
in 1989.

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 an original ZX81 program that doesn't work properly 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"
disk with a brief description regarding the failure. If XTender is to blame,
I'll try to fix it as soon as possible and you will get your disk back with
an updated version of XTender.


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 a Ph.D. student in 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 1993, 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...


ZX-91

Andre Baune is the editor of a small, monthly magazine called ZX-91,
intended for all the ZX81 users around the world. The magazine was first
released in 1991, when the ZX81 celebrated its tenth aniversary.
A quote from issue #1:

        "... I want to lift the spirit of the users and the believers
        in this marvelous little computer. I also want to reach the far
        away users and/or programmers. In this newsletter you will get
        print-out, pictures, and articles ..."

No ZX81-user can consider not subscribing to this newsletter! Besides small
programs and the latest news, it contains a large list of Sinclair/Timex
supporters, users groups and dealers who can still provide you with ZX81
hardware and/or software. Over 250 copies of ZX-91 #1 have already been sent
and more are being sent each month.
To obtain the latest issue, or more information, send a note together with
a self-addressed envelope plus IRC to:

        Andre Baune,
        304 Scott,
        Chateauguay, Quebec,
        Canada J6J 4H5.

And do me a favour, will you? Please mention where you got the information
about ZX-91 from!


XTENDER RELEASE HISTORY & FUTURE

Version   Date              Remarks

0.07      October 1991      First documented pre-release.

0.64      June 1992         Available via SIMTEL20 fileserver, New Mexico, USA.

0.93      January 1993      Current version.

< 1.00                      Successive 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      February 1993     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 !!

Any suggestions for the development of new, innovative PC software from
scratch are welcomed (assembly language programming only!).


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

    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 ***>
