(cC) Copyright Richard Teller 1984
Published by Hisoft 1984
180 High Street North
Dunstable, Bedfordshire, LU6 1AT  (0582) 696421
Ultrakit program code (c)Richard Teller 1984
All rights reserved. No part of this publication may be
reproduced or transmitted in any form or by any means,
including photocopying and recording, without the written
permission of the copyright holder. Such written
permission must also be obtained before any part of this
publication is stored in a retrieval system of any nature.
The information contained in this document is to be used
only for modifying the reader's copy of Ultrakit.
It is an infringement of the copyright pertaining to
Ultrakit and associated documentation to copy, by
any means whatsoever, any part of Ultrakit for any reason
other than for the purposes of making a security back-up
copy of the object code.


H I S O F T U L T R A K I T
CONTENTS
1. INTRODUCTION 3
2. USE OF THE KEYBOARD 5
3. ACCESSING COMMANDS 7
4. KIT COMMANDS 9
5. THE CLOCK 11
6. FIND AND SUBSTITUTE 13
7. PROGRAM TRACING 15
8. USER·DEFINED KEYS 17
9. KIT COMMAND INDEX 19
10. PRE—DEFINED COMMAND INDEX 27
11. CUSTOMISING THE TOOLKIT 29
12. GETTING STARTED (An introductory work·Session) 31

CHAPTER 1. INTRODUCTION
Ultrakit is an advanced, self—contained toolkit for the 48K
Spectrum. It may be loaded at any time before or after program
development and turns the Spectrum into a more sophisticated and
powerful machine for BASIC programming. Ultrakit offers features
more comprehensive than any toolkit currently on the market,
including full error trapping, ten user—defined keys, an alarm-
clock, program trace and many others. The kit is less than 7K in
size and sits just under the User—defined graphics area,
protecting these for the user.
Because of the degree of sophistication of Ultrakit, the
first—time user is strongly advised to read through the manual to
get a feel for how the kit functions. However, if after reading
the manual, some practical points remain unclear, Section 12:
Getting Started, offers an introductory tutorial in'the form of a
work session. The section gives instructions for loading and
activating Ultrakit, introduces many of the features and
facilities offered and will show by practical examples how the
kit may be used to aid your programming.


CHAPTER 2. USE OF THE KEYBOARD
The action of some of the keys on the Spectrum keyboard is
changed by Ultrakit. In particular, the SPACE and ENTER keys
become extra shift keys. Their auto—repeat is disabled and they
act not when pressed , but when released after pressing. As an
example, the printer may be turned on and off by pressing ENTER
and P together. The sequence of key presses should bez-
l. Press ENTER and hold. Nothing will happen.
2. Press P
3. Release ENTER before releasing P.
The message will appear.
4. Release P. The printer is now turned on/off.
The proceedure is identical when ENTER+K is used to obtain
K-mode and indeed this sequence should be followed whenever ENTER
or SPACE are used as shift keys together with another key.
Although this system may seem a little strange at first, it
is very easy to get used to, and soon becomes second-nature. The
key point is that the shift key should be released BEFORE the
other key. This system is used so that one does not have to be
exact in pressing two keys together in the way many other
toolkits demand.
A side—effect, however, is that the normal action of the
ENTER and SPACE keys is slightly altered. If desired, therefore,
the kit may be temporarily inactivated by the HIDE command (see
Section 9: Kit Command Index) to restore auto-repeat to these
keys.
The REM key, when used in immediate mode (ie.. not preceded
by a line—number) will produce the toolkit copyright message. No
other action is taken, and REM can be used exactly as normal.
Owing to the change in the SPACE key action, to break into a
program CAPS should be pressed slightly before SPACE.
Finally, a ”reset' can be obtained by pressing CAPS and then
SYMBOL SHIFT and SPACE together. This will break into any
program, and even machine-code 'lock—ups' while preserving all
programs and data.

CHAPTER 3. ACCESSING COMMANDS
Ultrakit uses two types of command. One type requires no
parameters (ie. information to work on), and is termed a Pre-
Defined Command (PDC). These com ands are obtained by pressing
ENTER together with one of the digit keys (see Section l0: Pre-
Defined Command Index).
The other type of command is termed a Kit Command. These
commands require parameters and are accessed by first pressing
REM in immediate mode (ie.. REM is first on the edit—line). This
produces the copyright message and the command may then be typed
in letter-by-letter (in upper or lower case) together with its
parameters (see Section 4: Kit Commands for details). The
command is only acted upon when ENTER is pressed and so all of
the normal Spectrum editing facilities will work as usual.
N.B. Pressing REM in immediate mode does nothing except
produce the copyright message and if desired the REM may be
deleted and another line entered in the normal way.

CHAPTER 4. KIT COMMANDS
There are 23 klt commands, and each starts with a unique
initial letter (a to w inclusive) (see Chapter 9: Kit Command
Index). To access the command it is only necessary that the
initial letter be the first character after the REM and thus the
full command, an abbreviation, or just the initial letter alone
may be used (in lower or upper case).
eg,. REM NUMBER I
REM nuM I will all have
REM N I the same effect
REM nit! I
If the first character after REM is not one of the letters
'a" to "w" then the message COMMAND NOT RECOGNISED is generated.
Kit commands are themselves divided into two types viz.
numeric and string (see the Kit Command Index to find which
commands are which). As may be apparent, numeric type commands
require numeric parameters to work on and vice versa.
A numeric parameter takes the form: SPACE integer
eg.. REM AUTO l0
and a numeric co mand may be followed by up to three numeric
parameters.
eg.. REM NUMBER l l0 l0
A string parameter takes the form: "string1 or
"string1\ or
”string1\string2
eg.. REM PUT'Hello\Goodbye
REM PUT'Goodbye
The '\” character is termed the string separator and the
separator may not appear in either string. It is however
possible to change the separator (with the Q kit command: see
Chapter 9: Kit command Index for details).
Although they are the string indicator, quotes may appear
anywhere else in the string parameter.
If the kit co mand is followed by the wrong parameter
indicator (ie.. a SPACE before a string command or a QUOTE before
a numeric command) or a numeric command contains non-numeric
characters, then the message BAD FORMAT is generated.

After a kit command has been executed, the parameters it
used are retained in a buffer, and become the current default
values.
eg,. REM MOVE 30 60 300 ENTER followed by
REM edit ENTER (no parameters specified)
will edit line 30, as 30 is the current default value for the
first numeric parameter. (The defaults for the second and third
are 60 and 300 respectively and all were set by the initial MOVE
command).
The INFORM kit command can be used to see what the current
default values are, and as INFORM is a numeric command, it can
itself be used to change the numeric parameters if required.
eg.. REM INFORM 1 2 3 ENTER
will display the current numeric parameters (which will be
1,2,3), string1, the current separator, and string2. (see also
Chapter 9: Kit Command Index for further details).
The PUT kit command is string type, and is used solely to
put strings into the two string buffers.
eg.. REM PUT”Hello\Goodbye
will make string1-Hello and string2·Goodbye.
N.B. In numeric parameters a SPACE alone may be used to
represent a default value. Thus if the current default values
are 1,10,400 then the command
REM NUMBER 5 (ie.. SPACE SPACE SPACE 5)
will use the parameters 1,10,5. The first two parameters were
not changed by the SPACEs but the third was altered. If the
command alone is entered
eg,. REM number ENTER
then all three default values are used unchanged. Before using
defaults, however, it is recommended that the user check the
values with the kit command INFORM.

CHAPTER 5. THE CLOCK
The clock will run independently of the normal Spectrum
operation and independently of whether it is displayed or not.
The clock-time display can be turned on and off by ENTER+8
(see Section 2: Use of the Keyboard) and can be updated by use of
the Kit command UPDATE.
eg., REM UPDATE"15:20 (NB Clock is 24 hour type)
The alarm—time display can be turned on and off by ENTER+9
and can be set by the kit command WARNTIME.
eg.. REM WARNTIME"18:00
The alarm will run for one minute when the clock time
reaches the alarm time, independently of whether either time is
displayed, and the alarm can be switched on and off by ENTER+0.
when the alarm is on, the letters AL will appear in the seconds
of the alarm time, otherwise ·— will appear.
If a variable TIME has been created then it will be
incremented by the clock 50 times a second. The following program
illustrates this feature:—
10 CLS: LET TIME=0: PRINT AT 0,0;"Four second wait"
20 PRINT AT l,0;TIM : IF TIME<-200 THEN GOTO 20
30 PRINT AT 0,l7;"over"
The clock is a background task that is interrupt—driven. In
the normal Spectrum, interrupts occur 50 times a second and have
been used by the programmer of the ROM to scan the keyboard and
update the system variable FRAMES (see Sinclair manual).
Ultrakit changes this system and uses interrupts in addition to
run the clock (among other things). Consequently, any operation
that disables interrupts will stop the clock for the duration of
the operation. Such operations include all the cassette and
microdrive handling routines (SAVE etc) and LPRINT. This should
be borne in mind if the clock is being used for accurate timing.
N.B. If the clock time and alarm time are both displayed
then Spectrum operations are slowed by about 15% and thus
displays should be switched off in a program where speed is
important.
N.B. Strange screen effects may very occasionally be seen if
both displays are on. These are unavoidable and are due to the
Spectrum being caught between one operation and the next.

CHAPTER 6. FIND AND SUBSTITUTE
These two kit commands can be used to search for and replace
occurrances of strings. The FIND string is string1 (the string
in the first string buffer), and the SUBSTITUTE string is
string2. These strings can be put into the respective buffers by
use of the PUT kit command (see Chapter Q: Kit Command Index),
and checked using the INFORM kit co mand.
The two commands FIND and SUBSTITUTE use an internal
pointer not affected by any other command and the pointer can be
set in the following manner:
eg.. To start the search at line 100 use
REM FIND 100 (This co mand will search for
string1 starting from line 100)
Normally both FIND and SUBSTITUTE will, when the next
occurance of string1 is found, print the line in which it occurs
in full with a flashing cursor showing the position of the
pointer and then return to BASIC. However, a minus sign in front
of the parameter will cancel this 'single-shot' mode and execute
the command "globally". what this means in practical terms is
that FIND will search through the whole program starting from the
pointer and display the results in the form ”line:statement' for
each occurrance of string1 and SUBSTITUTE will go through the
program starting from the pointer and change every occurrance of
string1 to string2 automatically.
eg.. REM FIND 100 will start searching at line 100 and
print in full the line containing the first occurrance,
whereas REM FIND -100 will start searching from line 100
and go through the whole program showing every occurrance as
linezstatement.
REM SUBST 100 will start searching at line 100,
will replace the first occurrance of string1 with string2 and
then print the line in full, as in FIND
whereas REM SUBST -100 will start searching from line 100
and will replace all occurrances of string1 with string2
automatically.
A typical use of these commands might be as follows:
REM PUT"Hello\Hi ENTER (FIND Hello SUBST Hi)
REM FIND -1 ENTER (Set pointer to line l and show
all occurrances of Hello in the program.
REM FIND 10 ENTER (Set the pointer to line 10 and
find the first occurrance of Hello after that line)
At this point, REM F ENTER will find the next occurrance of the
string Hello while REM S ENTER will substitute Hi for Hello and
display the result. Note that as SUBSTITUTE starts its search
from the pointer and FIND starts from after the pointer, one can
step through the program FINDing successive occurrances of
string1 (REM F ENTER) and then SUBSTITUTing them (REM S ENTER)
or not as required.
SUBSTITUTE may be used to substitute a variable for an
explicit number. As an example, having written a program you may
dicover that the constant 6.532 occurs twenty times and it would
make sense to save space and replace it with a variable (say x)
and then include the statement LET x·6.532 at the beginning of
the program. This is not normally possible with substitute
routines as they do not delete the invisible form of the number
(see Chapter 10). Ultrakit though, will do this and thus the
program will run normally after a substitution of this kind.
Note, however, that if you substitute PART of the number,
the invisible value will not be changed and the program will run
as though the change had not been made



CHAPTER 7. PROGRAM TRACING
Trace is activated by the kit command TRACE followed by
three numeric parameters. These are the trace—on line, the
trace-off line, and the initial speed of tracing (single digit).
Thus one can trace the whole program or select only a particular
problem ares.
Whenever trace is activated, the Spectrum will behave
completely normally if no program is being run. However, when RUN
or GOTO is the first statement in the edit-line and ENTER is
pressed,
eg,. RUN ENTER or RUN 100 ENTER or GOTO a+b ENTER
the program will execute one statement at a time at a reduced
speed, and the current line and statement will be printed in
inverse in the top right of the screen. (see Section ll:
Customising the toolkit).
While the program is tracing, there are three options open
to the user. He or she may break into the program as normal
although the break keys will only be noticed between statements
(N.B. The BREAK and ON_ERROR traps are inactive during TRACE).
In addition, the user may change the execution speed by pressing
one of the digit keys (1=full speed 6=one second delay 0=one
and a half second delay) or select single—step mode by pressing
SYMBOL SHIFT. These keys will also only be noticed between
statements.
In single-step mode, there are six options open. The user
may return to normal trace by pressing one of the digit keys, or
execute the next statement by pressing SYMBOL SHIFT. However, in
addition, the current variables may be listed by pressing V, the
current line may be listed by pressing L, the next line may be
listed by pressing N and the screen may be cleared by pressing C.
Trace mode inactivates the toolkit proper and the return to
the kit may be made by holding SYMBOL SHIFT and pressing SPACE.
NOTE TO MICRODRIVE USERS
Unfortunately, and despite much effort on our part, TRACE is
temporarily inactivated after microdrive commands (CAT, FORMAT,
MOVE, ERASE, LOAD/MERGE/SAVE/VERIFY *). After one of these is
executed, the program will run normally, but will not be traced.
Thus, if the user is tracing a program and hears the microdrives
start up, he or she should press BREAK note the line—number in
the message at the bottom of the screen and then type GOTO <that
line-number+l> to continue the trace.
NB. While in TRACE mode, the actual tracing may be
inhibited, if desired by putting a SPACE before the RUN or the
GOTO that is used to start program execution.
NB. If the initial speed selected is greater than 127 then
the trace will co mence in single—step mode.

CHAPTER 8. USER-DEFINED KEYS
The ten digit keys may be defined by the user to produce any
string required (up to a maximum of 256 characters per key) when
accessed. The effect will be as though the user had typed out
the string character by character.
The keys are defined by the KEY kit command:
eg., REM KEY"1 PRINT "Hello”|
REM KEY"0Goodbye
Note that the key number appears immediately after the string
indicator (quotes) and that quotes may appear freely in the
defined string. The vertical line at the end of the first string
is an implied ENTER (Symbol shifted S in E-mode). The word PRINT
is not typed in letter by letter, but is a keyword. To obtain
keywords in string parameters, K-mode can be forced by ENTER+K
(see section 2: Use of the Keyboard).
To access the user—defined string, press SPACE and the
required digit key together (as per section 2). In the above
examples, pressing SPACE+l would lead to the execution of the
command PRINT "Hello" and thus Hello would be printed, whereas
pressing SPACE+0 would lead to the string Goodbye being added to
the edit-line.
The User-Defined Keys may normally be accessed at any time
there is a flashing cursor in the edit-line, and so will work
during INPUT statements. However, the facility is turned off
temporarily by the kit commands AUTO, TRACE, and HIDE.
Note that although it is perfectly acceptable to produce kit
commands from user-defined keys
eg.. REM KEY"3 REM Number 1 10 10
ENTER must be pressed explicitly by the user and not implied by a
'|' character to execute the command. This restriction applies
only to kit commands.
EDITING USER-DEPINED KEYS
It is suggested that the user-defined keys are inspected and
edited in the following manner. Type in (or program a key to
produce) the string *REM KEY" (ie 5 key presses). Then type the
key number you wish to edit and then access the key. The string
may then be edited normally, and by deleting the *, the key can
be re—defined. Note that the presence of a flashing 2 after the *
will indicate that an implied ENTER was present in the original
string. lf there is a flashing ? then BASIC has attempted to
execute the line which has, of course, failed syntax and thus
there was an ENTER ("I") at the end of the line.

N.B A system of accessing the strings was chosen that acts
exactly as though the user had typed the characters of the string
in very fast. Thus when the string is accessed, a series of
clicks (or beeps depending on the value of the system variable
PIP) may be heard.
This system has two distinct advantages over most others.
Firstly and primarily it makes the process of inspecting and
editing the keys much easier for the user. Secondly, it
considerably broadens the scope of the facility as it allows
strings with more than one ENTER character in them. This in turn
means that information (perhaps in DATA statements or as User-
Defined Functions) may be saved with Ultrakit as program lines
and quickly retrieved and used after the kit is activated at the
start of the next programming session.
As an example, it is possible to program a key to produce
the relevant DATA statements for an entire set of user—defined
graphics and having saved this with the kit, to re—define the
user graphics at the start of the next program ing session with
the press of a key. The key concerned might be programmed with
the string:-
9997 DATA 1,2,3,4,5,6,7,8|::9998 DATA 9,10,11,12,13,14,15,16|::9999
DATA 17,18,19,20,21,22,23,24|::FOR N=0 TO 23: READ A: POKE USR
"a“+N,A:NEXT Nl
Note the use of two colons acting as dummy characters to use
up time while the Spectrum processes the entered line.
Experimentation will be required to find the correct number to
use.

CHAPTER 9. KIT COMMAND INDEX
In the following index, (P) after the co mand name means
that the output from the routine can be directed to a printer.
AUTO
Type: Numeric
Parameters: Increment
Use: REM AUTO 10
Used to facilitate program entry. After ENTER is pressed,
*increment* is added to the current line number and the result is
generated as a line number. If, after pressing ENTER, any other
key is pressed before the listing is complete then the generation
of the line number is inhibited. Thus another line may be
entered in another place in the program, generation inhibited
again, and then entry may be resumed at the original location.
Activation of AUTO temporarily inactivates the toolkit which
may be reactivated by holding SYMBOL SHIFT and tapping SPACE.
BREAK
Type: Numeric
Parameters: Line number
Use: REM BREAK 9980 REM BREAK -1 REM BREAK 0
If *line number* is greater than 0 and less than 10000 then
if break is pressed during a program, execution will immediately
resume at *line number*. If variables ERR, ERL, ERS exist they
will then hold 21 (see Sinclair manual) and the line and
statement where break was pressed respectively.
If *line number* is greater than 9999 and less than 65536
(eg.. -1-65535) then the break key will be disabled and will no
longer function.
If *line number*=0 then the break trap is switched off and
the break key will function normally.
It is possible to get into an infinite loop with the break
trap, but even this can be broken into by using the ”reset”
function. (CAPS+SYMBOL SHIFT+SPACE).
COPY
Type: Numeric
Parameters: Start of block line number
End of block line number
Destination line number
Use: REM COPY 100 400 5030
If any of the lines don‘t exist then the message LINE NOT
FOUND is generated. If *start* is greater than *end* or
*destination* lies between *start* and *end* then the message BAD
PARAMETER is generated. The block from *start* to *end*
inclusive will be copied after *destination* and renumbered in
1's starting from *destination* +1. Thus care must be taken to
ensure that sufficient line number space exists.
Note that only the line numbers will be renumbered and not

GOTO's etc. These must be changed by hand as required.
If the message OUT OF MEMORY is generated then the block
should be copied in smaller sections.
DELETE ·
Type: Numeric
Parameters: Start of block line number
End of block line number
Use: REM DELETE 500 760 · REM DELETE 1000 0 REM DELETE 0 0
If any of the lines don't exist then the message LINE NOT
FOUND will be generated. If *start* is greater than *end* then
the message BAD PARAMETER is generated. Otherwise, the block
from *start* to *end* inclusive is deleted.
A 0 as the first parameter will be converted to the first
line of the program and a 0 as the second parameter will be
converted to the last line. Thus REM DEL 1000 0 will delete from
line 1000 to the end and REM DEL 0 0 will delete the whole
program.
EDIT
Type: Numeric
Parameters: Line number
Use: REM EDIT 180
Will bring down a specific *line* for editing. The effect
will be exactly as though the user had moved the cursor to *line*
and then pressed CAPS+l (the edit key), thus Spectrum editing is
exactly as normal.
FIND (P)
Type: Numeric
Parameters: Line number to set pointer (and start search)
Use: REM FIND 100 REM FIND
See Section 5: FIND and SUBSTITUTE.
A string (sequence of characters) to search for must be present
in the string buffer (or have been PUT there eg.. REM PUT”string1
If a parameter is not specified with FIND then the current
default is used, but note that after use of a non-zero parameter,
FIND and SUBSTITUTE will enter zero into the first numeric
buffer. A parameter of zero will cause the search to begin (in
the case of FIND) from one character after the current pointer
position. This means that a sequential search through the
program is possible by initially setting the pointer to the first
line of the program and then repeatedly keying REM F ENTER to
find each subsequent occurrance.
When the string is found, the line in which it occurs will
be displayed with a character flashing to indicate the current
position of the pointer.
If a minus sign is put before the line number
eg.. REM FIND -100 then the pointer is set as normal, but ALL
occurrances of string1 after the pointer are shown in the form
LINE:STATEMENT
Used in conjunction with SUBSTITUTE.

GRAB
Type: Numeric
Parameters: Grab level
Use: REM GRAB 2 REM GRAB 0
Used to gain programming space by deleting parts of the
toolkit. *Grab level* can be 1,2 or 3. GRAB 1 loses the clock
and gains about 600 bytes for BASIC, GRAB 2 loses the clock and
FIND/SUBSTITUTE and gains in total about 900 bytes for BASIC,
GRAB 3 (or any other number) loses in add1tion,the Pre-defined
command MAP and GRAB itself and gains in total'over 1500 bytes
for BASIC. All GRABBED commands are subsequently ignored.
The system variable RAMTOP is not changed by the command,
but may, of course, be altered by the kit command REM RAMREL 0 to
gain maximum space.
HIDE
Type: N/A
Parameters: None
Use: REM HIDE
Temporarily inactivates the toolkit and can increase program
execution speed by about 5%. This command also restores auto-
repeat to the SPACE and ENTER keys. The kit may be re-activated
by holding SYMBOL SHIFT and tapping SPACE.
INFORM (P)
Type: Numeric
Parameters: None (but may be used to put numbers into the
numeric buffers)
Use: REM INFORM 10 10 10
will display the current default values for the three
numeric parameters, string1, the current separator, and string2.
JOIN
Type: Numeric
Parameters: Host line number
Tag line number
Use: REM JOIN 100 110 REM JOIN 420 420 REM JOIN 100 20
Will join *tagline* onto *hostline*. *Tagline* may be the
same as *hostline*. If the number of statements in the composite
line would exceed 127 then the command is aborted.
KEY
Type: String
Parameters: Key is defined by string1 (bar the first
character which will be the key number)
Use: REM KEY'1Hello REM KEY"0 PRINT "Hello'|
See Chapter 8: User—defined keys.

The key number (0 to 9) should precede the string desired, but
will not be included when the string is produced (see examples
above). The character "|" (symbol shifted S in E—mode) is
treated as an ENTER character enabling immediate execution of
commands. Thus a small program may be run
eg., REM KEY'0 FOR N=1 TO 10: BEEP .1,N: NEXT N|
If keywords are required then k-mode may be produced by pressing
ENTER+K.
If the string produced is a kit co mand ie.. starts with a
REM etc then ENTER must be pressed by the user and not programmed
into the string for the co mand to execute.
Note the strings are accessed by pressing SPACE+the required
digit key (see Chapter 2: Use of the Keyboard).
LOSE_KlT
Type: N/A
Parameters: None
Use: REM LOSE;KIT (must be typed exactly as shown)
If LOSE_KIT is typed after the REM then the kit will be
permanently inactivated. It may be re—activated by the relevent
RANDOMIZE USR xxxxx. (see Chapter ll: Getting started)
MOVE
Type: Numeric
Parameters: Start block line number
End block line number
Destination line number
Use: REM MOVE 50 160 6700
Move is exactly equivalent to COPY+DELETE and will thus copy
the block of lines, renumber them and then delete the original
block. See COPY.
NUMBER (P)
Type: Numeric
Parameters: Start line number
First new line number
Increment
Use: REM NUMBER 1 10 10
If *start line* is past the end of the program or *first new
line* is less than or equal to *start line* or the numbers would
exceed 9999 after renumbering, then the message BAD PARAMETER is
generated. The message OUT OF MEMORY is generated if there would
be insufficient room for the renumbered program.
Otherwise the program is renumbered from 'start line* to the
end with the first line number *flrst new number* and the value
*increment* between successive lines. All GOTO, GOSUB, LIST,
LLIST, RESTORE, RUN, and LINE statements are adjusted accordingly
and a report is given on all lines containing expressions after
the above tokens (eg.. GOTO a+b LIST 100/4 RUN) and on non-
existent lines.

0N_ERROR
Type: Numeric
Parameters: Line number
Use: REM ON_ERROR 9990 REM ON_ERROR -1 REM ON_ERROR 0
Exactly as for_BREAK except that all errors are trapped,
with the exception of 0:OK 9:STOP STATEMENT 14:BREAK CONT
repeats 21:BREAK INTO PROGRAM
If *line* is greater than 0 and less then 10000 then if any
error occurs in the program (barring the ones listed above) then
execution will immediately pass to *line*. If ERR, ERL, and ERS
exist then they will hold the error number (see Sinclair manual)
and error line and statement respectively. If *line* is greater
than 10000 and less then 65536 (eg..-1) then all errors in the
program will be ignored.
Both the error and break traps may be set and reset
independently.
Note that an infinite loop will occur if there is an error
in the GOTO line. The break key may be used as normal.
See BREAK.
PUT
Type: String
Parameters: String1 [(separator> string2] []-optional
Use: REM PUT'string1\string2
Used to put the FIND and SUBSTITUTE strings into the string
buffers. Separator may be changed by the kit command QSEP.
QSEPARATOR
Type: String
Parameters: First character of string1=new separator.
Use: REM QSEP', changes string separator to a comma.
Specifies the character used to separate string1 from
string2. Generally used if the current separator forms part of
the desired FIND or SUBSTITUTE string or is required as part of a
user-defined string.
RAMREL
Type: Numeric
Parameters: Relative change to RAMTOP.
Use: REM RAM -200 REM RAM 0
will change RAMTOP without CLEARing variables. Will not
allow Ultrakit to be invaded. The parameter is a relative move
eg.. REM RAMREL -300 will move RAMTOP down by 300 bytes.
REM RAMREL 0 will move RAMTOP up to the highest possible
value under Ultrakit to leave maximum space for BASIC.

SUBSTITUTE (P) .
Type: Numeric
Parameters: Line number to set pointer (and start search)
Use: REM SUBST 100 REM S 0
See Chapter 6: FIND and SUBSTITUTE
Used in conjunction with FIND. Generally one would FIND a
string and examine the displayed line to establish whether to
SUBSTITUTE. The action of SUBSTITUTE is to start searching from
the current pointer until string1 is found, replace it with
string2 and then display the line with a flashing character
marking the position of the pointer. Note that SUBSTITUTE will
start the search from the pointer whereas FIND will start from
after the pointer.
If a minus sign is put before the line number then the
pointer is set as normal but all occurrances of string1 from the
pointer onwards will be replaced automatically.
If string2 is null then all occurrances of string1 will be
deleted. This can be achieved by REM PUT”string1\ Typing the
command REM PUT"string1 would lead to the current default for
string2 being used.
SUBSTITUTE should not be used to change numbers, although it
may be used to replace them by a variable or to delete them.
See Chapter 6: FIND and SUBSTITUTE.
TRACE
Type: Numeric
Parameters: Start trace line number
End trace line number
Initial tracing speed
Use: REM TRACE 1 9999 5 REM TRACE 350 620 0
See Chapter 8: Program Tracing.
Executing the TRACE kit command will put the Spectrum into
trace—mode. In this mode, pressing ENTER when either RUN or GOTO
are first on the edit—line will activate TRACE. when the program
is running and the line being executed is between *start* and
*end* inclusive then the line and statement number will be
displayed in inverse at the top right of the screen (see Chapter
ll: Customising the toolkit).
The speed of program execution may be changed by pressing
one of the digit keys (0 to 9) where 1=full speed and 0=slowest.
Pressing SYM OL SHIFT will allow the user to single-step through
program statements by repeatedly pressing SYMBOL SHIFT.
While in single—step mode pressing
V displays all variables
L lists the current line
N lists the next line
C clears the screen
<digit> resumes the trace at the specified speed.
TRACE temporarily inactivatee the kit which may be re-
entered by holding SYMBOL SHIFT and tapping SPACE.

UPDATE
Type: String
Parameters: string1-new clock time in the form HH:MM
(Clock is of the 24 hour type)
Use: REM UPDATE”21:45
See Chapter 5: The Clock
VARIABLES (P)
Type: String
Parameters: string1
Use: REM VARSa REM VARS"*
Will display all variables starting with the first character
of string1. If string1 starts with a "*" then all variables are
displayed. FOR/NEXT and ARRAY variables are displayed in
capitals and the elements of arrays are not specified, only the
dimensions are given due to the often excessive size of arrays.
WARNTIME
Type: String
Parameters: string1-new alarm time in the form HH:MM
Use: REM WARN"22:05
See Chapter 5: The Clock
The seconds of the alarm time will be either == (alarm off)
or AL (alarm on). The alarm will sound and show as a flash for l
minute from the alarm time.

CHAPTER 10. PRE-DEFINED COMMAND INDEX
These routines are accessed by pressing ENTER+one of the
digit keys (see Section 2: Use of the Keyboard). They act
immediately and require no parametersc The routines will now be
discussed in turn.
 
These comprise CRUNCH1 - ENTER+l
CRUNCH2 — ENTER+2
REMKILL — ENTER+3
PACKER - ENTER+4
All four will generate the message "CAPS to quit SPACE to
execute' for safety, as all four will change the program in a
major way.
CRUNCH1 (ENTER+1) will convert all numbers to a dummy 0.
Whenever a number appears in a Spectrum program, the ASCII,
or character, representation is followed by an invisible number
marker byte and then five invisible bytes holding the value of
the number. (see chapter24 of the Sinclair Manual). When the
program runs, the processor is only concerned with the value of
the number and CRUNCH1 preserves that value, but puts a single 0
in place of the ASCII representation.
ie.. GOTO ZS becomes GOTO 0 and 1 byte is saved
Although the numbers now look to be 0, they still have the same
invisible value and the program will run normally (even a little
faster). Try it out!
Note that after running CRUNCH1, the real values are
unrecoverable and the line cannot be edited, or the dummy 0 will
turn to a real 0. It should only be used on a fully tested and
de-bugged program just prior to saving.
CRUNCH2 (ENTER+2) will save more space than CRUNCH1 but will
slow down program execution, and which of the two to use depends
on the program. It will convert 0 to NOT PI
1 to SGN PI
3 to INT PI
and all other numbers to their VAL equivalent.
ie.. GOTO 1 will become GOTO SGN PI with a saving of 5 bytes
(the invisible ones).
and GOTO 100 will become GOTO VAL *100* saving 3 bytes.

REMKILL.(ENTER+3) will delete all REM statements, control
codes (eg..colours etc) and unnecessary spaces from the program.
However, a REM statement may be protected for machine code (as
long as the REM is the first statement in the line) by putting a
* as the first character.
eg.. 1 REM * <machine—code here will not be deleted)
2 REM (machine code or anything else here will>
3 PRINT : REM * (so will anything here)
PACKER (ENTER+4) will compress the program into as few
statements as is logically possible (with a maximum of 127
statements per line). It will not tag a line onto the one before
if the one before has a REM, STOP, IF, GOTO, RUN, or RETURN in it
and nor will it tag the line if the line itself is referenced
EXPLICITLY anywhere else in the program by a GOTO, GOSUB, LIST,
LLIST, RESTORE, RUN, or LINE. Note that expressions, however
simple they are will not be picked up.
eg.. GOTO 100+1 and RUN VAL "100" are ignored
Thus to compress your program into the minimum possible
space one should first do a REMKILL. Then reNUMBER the program
starting at l in l's. Then do a PACKER and finally one of the
CRUNCHes - It is very important to LEAVE THE CRUNCHES TILL LAST
as they will render the expression after any GOTO's etc
unrecognisable by NUMBER and PACKER and program flow will become
corrupted. It is strongly recommended that the user first saves
an uncompressed version of the program.
MAP (ENTER+5) will produce a memory map of the Spectrum and
will copy the screen to the printer if the printer is turned on
(see Chapter ll: Customising the toolkit)
L—CASE (ENTER+6) will convert all variables to lower case.
U—CASE (ENTER+7) will convert all variables to upper case
Note that the Spectrum does not distinguish between upper
and lower case variables eg.. LET N=5: PRINT n
CLOCK—TIME (ENTER+8) will switch the clock—time display
on/off (this will not affect the alarm)
ALARM—TIME (ENTER+9) will switch the alarm-time display
on/off (neither will this)
ALARM-SOUND (ENTER+0) will switch the alarm on/off. If the
alarm is on AL will appear in the seconds of the alarm—time,
otherwise == will appear.

CHAPTER 11. CUSTOMISING THE TOOLKIT
The addresses that follow allow the user to produce a
customised version of Ultrakit which may then be saved with the
instruction SAVE "ULTRAKIT"CODE 58178,7179.
[For microdrives: SAVE *"M";1;"ULTRAKIT"CODE 58178,7179]
64784 Microdrive owners MUST poke this with 124.
(Normally it holds 71)
58389/58390 The displacement from the start of the
display file where the clock—time is printed.
To work out what to POKE into these addresses
to put the clock at row R, column C, run the
following programz-
10 INPUT "ROW ";R
20 INPUT "COL ";C
30 LET OFFSET=0
40 IF R>=B THEN LET R=R—8: LET OFFSET=2048
50 [F R>=8 THEN LET R=R—8: LET OFFSET=4096
60 LET AD=OFFSET+R*32+C
70 LET ADLO=AD—256*INT(AD/256)
80 LET ADHI=INT(AD/256)
90 PRINT "POKE 58389,";ADLO
100 PRINT "POKE 58390,";ADHI
58399/58400 The displacement for the alarm time.
See above.
58537 POKE with 0 to put clock and alarm in normal
video. POKE with 47 to set to inverse.
59388/59389 If you have a Spectrum printer then when it
is switched on, the Pre—defined command MAP
will copy its output to the screen. If you
have another type of printer then this
address should be POKEd with your printers
copy address, low byte first.
eg.. If the copy routine address is at 23760
then POKE 59388,23760—255*INT(23760/256)
POKE 59389,INT(23760/256)
and then the copy in MAP will work normally.
63407 Row at which TRACE will be printed (0-24).
63426 Column at which TRACE will be printed.
63388 POKE 0 for TRACE in normal video, 47 for
inverse.

N.B. When the kit is saved, the User—defned key strings are
saved as well and thus it is possible to save information and
small programs with the kit. See Chapter 8: User-defined Keys.
eg.. REM KEY"l PRINT ""RUNNING "MYPROG""": CLEAR 40000: LOAD
'MYPROG': RUN|
REM KEY"09999 DATA 1,2,4,8,16,32,64,128|:: RESTORE
9999: FOR N-0 TO 7: READ D: POKE USR "a"+N,D:NEXT N: PRINT
"GRAPHIC A IS NOW ":CHR$ l44|
As can be seen in the second example, it is possible to have
lines with more than one ENTER implied in them. However, if this
is attempted, then about two colons should be inserted to give
the Spectrum time to process the line. If this is not done, then
characters are often lost from the accessed string.

CHAPTER 12: GETTING STARTED (An introductory work—session)
Before using this work—session, it is strongly recommended
that the user read through the preceeding chapters especially
chapter 2.
To load Ultrakit type CLEAR 58177: LOAD ""CODE ENTER and
then start the tape.
If you do not have microdrives attached to your Spectrum
then you should now activate Ultrakit by the command RANDOMIZE
USR 65212. If you do own a microdrive then you should (as per
Chapter 11) first POKE 54784,124 and then activate Ultrakit by
RANDOMIZE USR 65210.
Firstly, you can display the clock time by pressing ENTER+8.
This should be done as described in Chapter 2 by pressing ENTER
and holding, pressing 8, releasing ENTER, and then releasing 8.
The clock time should now have appeared in inverse in the lower
right screen. Do the same now for the alarm time with ENTER+9.
You will see that == appears in the seconds of the alarm time
indicating that the alarm is switched off. You may switch it on
by pressing ENTER+O.
The clock time may be set using the kit command UPDATE. Kit
commands must be preceded by REM so press REM and hold it down.
You will see the kit copyright message
Release REM and type UPDATE“15:22
(or whatever the ime is) and then press ENTER. The alarm time
may be set in exactly the same way with the kit command WARNTIME,
so type REM WARNTIME”22:O0 (or whatever time you want to stop
computing at). Note that once you have become more familiar with
Ultrakit you will not need to type out the whole of the kit
command but only an abbreviation. Verify that REM w”23:O0 will
also set the alarm time. Now switch the clock and alarm times
off by ENTER+8 and ENTER+9. The alarm will still sound at the
correct time even though the time is not displayed.
Now look at the memory map of the Spectrum by pressing
ENTER+5. Note that the size of the program is 0. Press any key
to get back to BASIC and type in the line
10 LET A=0
Now look at the map again and note that the program size is now
15 bytes. These are 4 for the line number and line length, 4 for
the ASCII characters LET A = 0, 6 for the hidden value 0, and 1
for the ENTER at the end.
If you run the program, you can see that the variables area
is now 7 bytes long. This is l byte for the A, 5 bytes for its
value and 1 byte for the 128 that is always present at the end of
the variables area.
It is often advantageous to define some keys at the
beginning of a programming session and one can do this with the
kit command KEY. After checking through Chapter 8 and entry
under KEY in Chapter 9, enter the line
REM KEY"l FOR N=-20 TO 20: BEEP .01,N: NEXT N|
The FOR and the NEXT should not be typed in letter by letter, but

are keywords. To get K-mode, you should press ENTER+K. Note the
"|" on the end (symbol shifted S in E-mode) that will act as an
ENTER character. Now to access the string you have just defined
you should press SPACE+1 (as described in Chapter 2). Perhaps it
is now better to program key 1 with a more useful string so enter
the line
REM KEY"1 REM NUM ER 1 10 10
The second REM is got via forcing K-mode and now accessing key 1
and then pressing ENTER will renumber the current program.
Another useful string is
REM KEY"2 REM EDIT (there is one space after EDIT)
and now pressing SPACE+2 and then entering the line number will
enable you to edit any line without first having to move the
cursor around.
Now you can generate some program. If you know roughly what
you are going to be writing then life is much easier using the
AUTO command to generate the line numbers for you. For AUTO you
need to specify the increment between lines and normally the
command will be
REM AUTO 10
After executing this command, start to enter the program below by
typing the first line in normally. Note that after you press
ENTER the next line number is generated for you. Enter the whole
program and note that you can use REM normally. Also note that
during AUTO mode, the kit proper is switched off. when the
program is entered, delete the l0O that would have been the next
line—number, then hold SYMBOL SHIFT and tap SPACE to re—enter the
kit (this is signalled by the printing of the copyright message).
l0 PRINT "TEST”: PRINT
Z0 PRINT "PROGRAM"
30 FOR N=1 TO 100: LET A$=STR$ N
40 LET BS=B$+A$: LET A=N*N
50 DIM Q(N,N)
60 PRINT AT 10,10;N
70 NEXT N: PRINT "FINISHED"
80 STOP
90 REM THIS IS A TEST
Having typed this you will of course notice that line 40 will
generate the error VARIABLE NOT FOUND for B$ so that you want to
edit (say) line 30. You can now do this by accessing key 2 and
then typing 30 ENTER (assuming you programmed it before as shown)
or typing in
REM EDIT 30 ENTER
Now change line 30 and insert LET BS="" at the beginning.
Although this is not a large (or sensible) program, it is
possible in a larger one that you might want to change all
occurrances of PRINT to LPRINT. To demonstrate how to do this
(and the same would apply to finding and substituting longer
strings of characters) firstly type in

REM PUT' PRINT\ LPRINT ENTER
Note that print is a keyword that is got via k-mode (ENTER+K).
The "\" is symbol shifted D in E-mode and is the string
separator ie.. Ultrakit uses it to detect when the first string
has ended and the second has started. The effect of this command
will be to put PRINT into the first string store or buffer and
LPRINT into the second. Their presence there can be checked by
typing
REM INFORM ENTER
This will show the values in the three number stores or buffers,
the contents of the first string buffer (string1), the current
string separator ("\"), and the contents of the second string
buffer (string2).
Having read Chapter 6 you will know that FIND searches for
string1 (PRINT at the moment) and SUBSTITUTE will replace it with
string2 (LPRINT). Now execute the kit command
REM FIND -1
This will set the search pointer to line l (or the next one
after) and because of the "-" will run through the whole program
displaying all occurrances of string1 as LINE:STATEMENT. The
output should look like
10:1
10:2
60:1
70:2
If a positive line number is used then the find will be "single—
shot". Try the command
REM FIND 1
Line 10 should be printed on the screen with a flashing character
marking the position of the search pointer. Now pressing REM F
ENTER will find the next occurrance, while REM S ENTER (short for
REM SUBSTITUTE ENTER) will find the next occurrance and replace
it with LPRINT. However, as SUBSTITUTE starts its search from
the pointer one can first do a FIND and then SUBSTITUTE the found
string. FIND starts to search from l character after the pointer
so it will always move forward through the program. Experiment
with this.
Assuming that you would now like lines 10 and 20 to appear
at the end of the program, this is a convenient time to introduce
the block functions. Executing the command
REM MOVE 10 20 90
will move lines 10 and 20 and put them after line 90, will then
renumber the lines 91 and 92 and will then delete lines 10 and
20. If the command had been COPY with the same parameters then
lines 10 and 20 would have been left. A block of lines can be
deleted thus
REM DELETE 91 92

The program is now not quite as tidy as it first was in terms of
line numbers, but this can be altered by use of the NUMBER kit
command. Execute the command
REM NUMBER 1 10 10
(or produce it via key 1). This will renumber the program
starting from line l, with the first new number 10 and the
increment 10. This is a very flexible command as it will alter
all explicit GOTOs etc and give a report on all calculated GOTOs
eg.. GOTO 100*a or GOTO up and on all GOTOs etc that refer to
non-existent lines. This facility may bring to light errors that
would not otherwise have been noticed.
If the program is now run then it is impossible to see what
is being done unless the break key is continually pressed and
variables are investigated. However, the TRACE kit command is
used for just this purpose. Execute the co mand
REM TRACE 1 9999 5
You are now in trace mode and when the program is run trace will
be active over the whole of the program and will operate at an
initial delay of 5. Now type either RUN or RUN 10 or GOTO 10
(making sure that the keywords are the first on the edit-line)
and the program will start to run, but will go very slowly and
display the line and statement that has just been executed in
inverse at the top right. Check that pressing the digit keys
will lead to different speeds of program execution and then hold
down SYMBOL SHIFT. This will enter single-step mode and
execution will stop until you press either a digit key to return
to normal trace or SYMBOL SHIFT again to execute the next
statement. However, in the meantime four other options are open.
You can press V to list the variables, L to list the current
line, N to list the next line or C to clear the screen. None of
these commands will execute any of the program and you can resume
single-stepping when required. Press digit key 1 to quit single-
stepping and resume execution at full speed and either wait for
the program to end or press break.
It is perfectly possible to look at the variables from
outside trace and so re-enter the toolkit proper by holding
SYMBOL SHIFT and tapping SPACE (this is required only after
TRACE, AUTO, and HIDE). Type in the command line
REM VARIABLES"*
This will display all the variables, but note that one may
specify the initial letter thus
REM vars"n
will only show those variables beginning with n.
Finally, it is worth seeing how much space can be saved by
the compaction·routines in Ultrakit. After reading Chapter 10,
press ENTER+5 and note down the program size. Now press ENTER+3
to remove the REM statement, and then ENTER+4 to pack the
program, and then ENTER+2 to do a CRUNCH2. Now you can see
(ENTER+5) that even in this small program quite a few bytes can

be saved, but note also that the program is now nigh on
impossible to debug, and so these routines should only be used on
a fully debugged program prior to execution.
Hopefully, this work-session has given you an idea of the
huge potential that Ultrakit has to speed your programming up and
smooth the way towards polished programs. Many of the features
have not been discussed, but all the conmands are detailed in
Chapters 9 and 10, and_extra information is present on these and
other matters in the preceding chapters. Good luck.
RICHARD TELLER
TECHNICAL NOTE
Ultrakit works by vectoring interrupts and using them to run
its tasks. This means that any machine-code program that uses
interrupts is not compatible with Ultrakit. You should in this
instance use the LOSE_KIT command and then re-activate the kit
when required with the relevant RANDOMIZE USR xxxxx. The use of
this type of system also means that the NEW com and from BASIC is
not advisable as it will switch off Ultrakit (by resetting normal
interrupt mode) which will again have to be activated by a
RANDOMIZE USR xxxxx. Instead of NEW, we suggest that the
programmer uses the kit command REM DELETE 0 0 to remove the
program and then CLEAR to remove all variables.

 
SUMMARY OF ULTRAKIT
KIT COMMANDS PRE-DEFINED COMMANDS
(S)-String type ENTER+K - K-MODE
(P)-Printer output P - PRINTER ON/OFF
AUTO 		1 - CRUNCH1
BREAK 		2 - CRUNCH2
COPY 		3 - REMKILL
DELETE 		4 - PACKER
EDIT 		5 - MAP (P)
FIND (P) 	6 - LOWER CASE
GRAB 		7 - UPPER CASE
HIDE 		8 - CLOCK TIME SWITCH
INFORM (P) 	9 - ALARM TIME SWITCH
JOIN 		10 = ALARM SWITCH
KEY (S)
LOSE_KIT 	CAPS+SYMBOL SHIFT+SPACE = "WARM RESET"
MOVE 		SPACE+<digit> - USER-DEFINED KEY ACCESS
NUMBER (P)
ON.ERROR
PUT (S)
QSEPARATOR (S)
RAMREL
SUBSTITUTE (P)
TRACE
UPDATE (S)
VARIABLES (P)(S)
WARNTIME (S)


OTHER ZX SPECTRUM SOFTWARE FROM HISOFT:
HISOFT DEVPAC
The most powerful machine code development system for the ZX
Spectrum. The assembler (GENS) includes all the usual facilities plus
macros, the ability to 'include' text from tape or microdrive, so that any
size of object code can be produced. The full range of arithmetic
operators is available. The powerful editor includes search and replace
facilities.
The disassembler/debugger (MONS) gives you a 'front panel' display of
the Z80 registers, a block of memory and a dissassembly of the current
instruction. Commands include single step (even in ROM), breakpoints,
modifying memory etc. The disassembler produces labels and can
produce a textfile for use by the assembler. '
Both GENS and MONS are fully relocatable and come with a
comprehensive 45 page manual.
HISOFT PASCAL
Hisoft Pascal is an almost full implementation of Standard Pascal with
additional procedures and functions for use on the ZX Spectrum. Hisoft
Pascal makes it easy to write well structured programs that are easy to
modify, and transport to other Z80 systems. The object code produced
runs typically 40 times faster than the equivalent ZX Basic program.
Unlike most other advanced |anguages,more than 20K of memory is free to
the user. The ability to compile from tape or microdrive and to produce a
program that will run without the compiler present makes it possible
to write very large programs.
lt is possible to save variables to tape or microdrive, to peek and poke any
size variables, and include your own inline machine code. Turtle graphics
procedures which make creating graphical displays easy are also supplied.
The same powerful editor used with the assembler is supplied to edit
Pascal programs.
Hisoft Pascal comes complete with a 70 page user manual. n
UK prices:
HISOFT DEVPAC £14
HISOFT PASCAL £25
Overseas customers please contact us for prices.
Hisoft, 180 High Street North, Dunstable, LU6 1AT, Tel: (0582) 696 421