Ae oa

UNDERSTANDING YOUR SPECTRUM

BASIC AND MACHINE CODE PROGRAMMING

DR.IAN LOGAN

‘Zk Spectrum

UNDERSTANDING YOUR SPECTRUM

BASIC AND MACHINE CODE PROGRAMMING

by

Dr. lan Logan

Lincoln, England 1982

aa Melbourne House Publishers

Published in the United Kingdom by: Melbourne House (Publishers) Ltd., Glebe Cottage, Glebe House,

Station Road, Cheddington,

Leighton Buzzard, Bedforshire, LU7 7NA, ISPEN O 86161 111 X

Published in Australia by:

Melbourne House (Australia) Pty. Ltd.,

Suite 4, 75 Palmerston Crescent

South Melbourne, Victoria, 3205,

National Library of Australia Card Number and ISBN 0 86759 114 5

Published in the United States of America by: Melbourne House Software Inc.,

347 Reedwood Drive,

Nashville NT 37217,

Copyright (c) 1982 by Dr. Ian Logan All rights reserved. This book is copyright. No part of this book may be copied or stored by any means whatsoever whether mechanical

or electronic, except for private or study use as defined in the Copyright Act. All enquiries should be addressed to the publishers

Printed in Hong Kong by Colorcraft Ltd.

Preface

It is almost impossible. to believe that within the space of only 2% years SINCLAIR RESEARCH of CAMBRIDGE has manufactured and sold about 500,000 microcomputers. It was in the spring of 1980 that the revolutionary ZX80 was launched. The machine was an instant success as it was the first really cheap microcomputer for the hobbyist. However, within only one year Clive Sinclair and his team were ready with the 2X81. This model was a great improvement on the ZX80 and took the development of a microcomputer with a low resolution, black and white display to a stage that is never likely to be attained again.

But now we have the ZX SPECTRUM. This machine has been developed directly from the ZX80 and 2X81, and by so doing Sinclair Research has produced a microcomputer with a superb High Resolution and Colour display.

It is, however, with some regret that the ZX80 and 2X81 have been superseded as they were both beautiful machines. They had a simplicity of operation that made them a pleasure to program. This does not mean the SPECTRUM is a difficult machine to use but | do feel that in order to get the “best’ from the new machine it will now take longer to write ‘finished’ and ‘polished’ programs.

This book has been written so that the reader can ‘go beyond’ the two fine manuals that come with the actual machine, and thereby develop a deeper ‘understanding’ of both the SPECTRUM and microcomputer systems in general.,

I wish to acknowledge the help given to me by:

Alfred Mitgrom

The president of Melbourne House (Publishers) who has such a keen interest in microcomputing and who has done a great deal to advance the ‘Sinclair’ machines world-wide.

Dr. Frank O'Hara My co-author on the ‘Sinclair ZX81 ROM Disassembly: Part B’ from whom | have learnt so much about the ‘calculator routines’.

Nigel Searle The head of the computer division of Sinclair Research who kindly sent me a SPECTRUM in June 1982,

And my wife Liz and my two daughters Jackie and Carolyn, who have had to endure the writing of this book.

Contents

Preface

Chapters

. The SPECTRUM microcomputer system

. The BASIC commands and functions

. The Z80 microprocessor

The mathematics of machine code programming . The Z80 machine code instruction set Demonstration machine code programs

. An outline of the 16K monitor program

Using the monitor program's subroutines

ONONARWNHR

Appendices i. Tables of 280 machine code instructions ii. DECIMAL-HEXADECIMAL conversion tables iii. Currently available machine code handling programs iv. SPECTRUM ‘bugs’

Pages

22 47 60 71 110 135 159

180 186 188 189

1. UNDERSTANDING The SPECTRUM microcomputer system

1.1 Making a start

It is always fun to dip into a book, opening it here ..., and there .. .; but computers are the most logical of machines and everyone trying to improve their ‘understanding’ should start ‘here’ at the beginning.

1.2 Three views of the machine

{t is possible to describe any microcomputer system by taking three different views of the system.

The first is an overall ‘system’ view which will encompass the actual microcomputer and all its attendant peripherals. The second view is of the ‘physical’ parts of the microcomputer itself.

The third view is obtained by looking at the ‘logical’ workings of the microcomputer system.

The ‘system’ view is probably already familiar to most readers but it is included as there will be some people who are unfamiliar with the SPECTRUM system.

1.3 The ‘system’ view

The SPECTRUM microcomputer itself is a black plastic box of width 233 mm., depth 144 mm. and height 30 mm. On the top surface are the forty rubber keys that form the keyboard. Along the rear edge are, from left to right, the output socket that connects to the T.V. aerial input, the input socket that connects to the cassette player output, the output socket that connects to, the cassette player input, the expansion port that may be joined to the printer, to the microdrives and other input/output devices, and finally the power socket.

The main printed circuit board with the Z80 microprocessor and the other electronic components, including the single loudspeaker, is found within the black box but separate from the keyboard. The main board and the keyboard are linked by two ribbon cables.

The system can be shown diagrammatically see diagram 1.1.

Although the system will ‘run’ without the T.V. display it is not the manufacturer’s intention that this be done as all the ‘system reports’ appear on the T.V. display and cannot easily be made to appear on the printer, or any other peripheral.

1.4 The ‘physical’ view

The main board of the SPECTRUM can be easily inspected by first removing the five retaining screws on the under surface of the black box and then

vi

eo 060900

T.V. DISPLAY

MAIN BOARD

KEYBOARD —+

EXTENSION CONNECTOR

for: printer, CASSEL TE microdrives, {input/output switches. a_o |

J

POWER INPUT

Il Af

| easly

1 doll LOUD- ian SPEAKER 1 1 Lal oobooco000d ooonAnAaaAdg foooooroggAd maadagoog

Diagram 1.1 The SPECTRUM microcomputer system {not to scale)

8

lifting up the upper half of the box. Care must be taken as the upper part of the box contains the keyboard and it is linked to the main board by two rather fragile ribbon cables. These cables may be pulled out of their sockets but it is not the author's advice that this be done, unless necessary, as the cables may be damaged. The use of two equal length pencils as ‘stays’ can also be helpful.

The major components found on the main board are shown in diagram 1.2.

Each of the major components will now be discussed in turn:

The Z80 microprocessor

This silicon chip is the most important of all the components. It is a ‘micro- processor’ and as such itisa machine capable of acting as a ‘computer’ which in a widely accepted way is ‘a machine capable of follawing a stored pro- gram’. The program for a Z80 microprocessor will always be in the form of a set of Z80 machine code instructions and any associated data.

In the SPECTRUM the Z80 microprocessor is ‘clocked’ at 3.56 MHz and at that speed is capable of processing 875,000 of the more simple machine code instructions a second. It is interesting to note that at any time that the correct ‘power’, ‘ground’ and ‘clock’ connections are made, the microproces- sor will be working. However the results of its work will be ‘nonsense’ unless the microprocessor is following a sensible machine code program.

The 16K ROM (= read only memory) The machine code program that is normally followed by the Z80 micro- processor is supplied by Sinclair Research in a ‘read only memory’ chip that holds 128K bits, or 16K bytes, of information.

In the ‘16K monitor program’ of the SPECTRUM roughly 7K is allotted to the ‘operating system’, 8K to the BASIC interpreter and the 1K remaining to the ‘character generator’.

The 16K of RAM (=random access memory)

in the standard 16K version of the SPECTRUM there are eight 2K byte, or 16K bit, memory chips, whereas in the 48K version there is an additional 32K of memory.

Three of the eight memory chips form the ‘memory mapped display‘ and would normally only be used for this purpose. The fourth memory chip is devoted to holding the attribute bytes for the 768 character areas of the display and the system variables. A little over 8K of RAM is left free in the 16K version.

Expansion

T.V. modulator connector Keyboard data input Se | Keyboard PAL Cassette : | address encoder connections Z80 microprocessor output \ / \ 16K ROM Power input + 4 rr aS i

a Y i ! |

pale mee ees ea 2 I

| | | || !

| I |

} I

| | 1 I U

i Loudspeaker Heatsink 16K of RAM 32K of RAM optional (4000h-7FF Fh) (8000h-F FFFh)

Diagram 1.2 The major components of the SPECTRUM’S main board (Issue Two)

10

The SINCLAIR ULA {=uncommitted logic array)

This chip can be considered as being a large chip made up of many smaller chips. In the SPECTRUM the ULA is largely concerned with the scanning of the ‘memory mapped display area‘ and the ‘attribute area’ to produce the T.V. signal.

The PAL encoder This chip receives the ‘colour’ information from the ULA and uses it to prepare the required signal for the UHF modulator. The signal produced from the modulator is nominally on channel 36 in the U.K. version of the SPECTRUM.

In addition to these major components there are the loudspeaker, the heat sink, the voltage regulator, the system clock, various address decoders and buffering chips and a modest number of other minor components.

1.5 The logical view

In this view the links between the various components of the microcomputer system are considered. These links do have a real existence they are tracks on the printed circuit board, or even actual wires but it is the use to which these links are put that has to be understood.

A Z80 microprocessor can generate an individual address for 65,536 different memory locations (64K). The limit on the amount of memory that can be linked to a 280 microprocessor, in a straightforward manner, is therefore 64K. In the standard 16K SPECTRUM only the locations with the addresses, in decimal, from 0 to 32,767 are available to be used. Whereas in the 48K SPECTRUM all of the addresses from O to 65,535 actually address memory locations.

In the SPECTRUM, addresses are produced in the form of 16 binary signals. The address of location Q is thereby 0000 0000 0000 0000 and that for location 65,535 is 1111 11111111 1111. The addresses are generated by the Z80 microprocessor and are carried around the computer on an ADDRESS BUS. There are 16 lines, or tracks, on the address bus of the SPECTRUM and an address will be specified by considering which of the lines carry a ‘high’ voltage and which carry a ‘low’ voltage. Because an address requires 16 binary signals it can also be described in ‘two bytes’, each of eight bits.

Whereas the address bus has 16 lines, the DATA BUS of the SPECTRUM has only eight lines. Therefore any data, whether it be a machine code in- struction or a byte of data proper, can only be considered as being in the decimal range of 0 to 255, or the binary range of 0000 0000 to 1111 1111.

Diagram 1.3 shows a simplified view of how the address bus and the data bus are linked to the other major components of the SPECTRUM. The diagram also shows how it is possible to consider the ‘ULA chip’ as viewing

11

16 line ADDRESS BUS / /

i 16/48K 4

z80 RAM i pigs

ROM

Lower 6K of RAM are ‘viewed’ from this side. to give the T.V.

picture.

T } B line DATA BUS \

Data output to Date input from: cassette player, keyboard, microdrive, cassette player, printer. microdrive,

printer.

Diagram 1.3 The ADDRESS and DATA buses of the SPECTRUM system.

12

the 6k of memory reserved for the display ‘from the other side’ to that viewed by the Z80 microprocessor.

As part of this ‘logical view’ of the SPECTRUM it is also appropriate to consider the normal mode of operation of the system and discuss the ‘memory map’.

The SPECTRUM is supplied by SINCLAIR RESEARCH with a 16K Monitor program that provides the user with an operating system and a BASIC interpreter. It is indeed possible to leave this monitor program and have the Z80 microprocessor execute one’s own machine code program if desired. In normal use the operating system of the SPECTRUM does not require any action on the part of the user and all the actions of the operating system are said to be ‘transparent’ to the user. Therefore, it appears that whenever the SPECTRUM is in use, it is the BASIC interpreter part of the monitor program that is being executed. The user is able to enter immediately BASIC program lines or execute BASIC programs. In a way of thinking, the Operating system considers the BASIC interpreter as a subroutine that is to be ‘run’ as required; and the BASIC interpreter considers the jine, or lines, of a BASIC program as containing instructions that direct it to ‘run’ the required subroutines of the interpreter.

Note that in no way does the Z80 microprocessor itself execute a BASIC Program but only the monitor program that is in Z80 machine code. The only exception to this occurs when a user-written machine code program is being executed.

The memory map of the standard 16K SPECTRUM is outlined in diagram 1.4 and each of the ‘areas’ will now be discussed briefly.

The ROM area

The 16K ROM containing the operating system, the BASIC interpreter and the character generator occupies the locations decimal 0 to 16,383, hex. 0000-3FFF. As in any Z80 based microcomputer system, the start of the machine code program is found at location 0.

The memory mapped display area

The 6K of memory from locations decimal 16,384 to 22,527, hex. 4000- S7FF, form the ‘high resolution’ display area. It is important to realise that this ‘area’ is fixed by the hardware of the SPECTRUM and cannot be altered under software control.

There is a one-to-one relationship between all the bits in this memory area and the pixels of the T.V. display and the following calculation shows that the number of bits in 6K of memory does equal the number of pixels of the display.

13

LOCATION ADDRESSES

decimal hex.

SYSTEM VARIABLES

32,767 7FFF =~

32,600 7F58~,,

User-defined graphics area

32,599 7F57-7

GO SUB stack

Machine stack

23,734 SCBG~ _ 23,552 5COO = - 23,296 5B00-»_. 22,528 5800-3__

16,384 4000 __

spare bytes

Calculator stack

Work space

Editing area

Variables area

-eP-RAMT

_ UDG “~RAMTOP

stack pointer e pi

ST REND

STKBOT

WOR KSP

EB LINE

VARS ~~

BASIC program area

Channel information area

Microdrive maps

7 PROG

CHANS

System variables area

Printer buffer

Attribute area

Display area

ROM area

0 0000-3

Diagram 1.4 The memory map of a 16K SPECTRUM

14

No. of bytes in 6K of memory = 1,024 * 6 = 6,144

No. of bits in 6K of memory = 6,144 * 8 = 49,152

No. of pixels in a 32 column by 24 line display with 64 pixels/character = 32 * 24 * 64 = 49,152

The relationship between the memory bytes and the character areas of the T.¥. display is very straightforward but does lead to confusion.

Initially, consider the T.V. display in thirds. The top third of the display, lines O to 7, is produced by scanning locations decimal 16,384 to 18,431, hex. 4000-47FF. The middle third, lines 8 to 15, by locations 18,432 to 20,479, hex. 4800-4F FF; and the bottom third of the display, lines 16 to 23, by locations 20,480 to 22,527, hex. 5000-57F F.

Next, consider each of these 2K blocks as consisting of eight %4K areas. The first of these smaller areas in each of the three blocks contains the bits for the top lines of the 256 characters in its third of the display, the second area the bits for the second lines of the characters, and so on for the eight lines of all the characters. This relationship applies to all of the 24 “K areas in the display area.

The attribute area

The T.V. display has 768 character areas, each of which can have one of eight PAPER colours, eight INK colours, be FLASHing or steady, and be BRIGHT or normal.

The locations from decimal 22,528 to 23,295 hex. 5800-5AFF, are used to hald the data that determines the current attributes for the display.

The relationship between the character areas and the attribute bytes is uncomplicated as the bytes are scanned so as to give the appropriate value for the characters on the top line of the T.V. display, going from left to right, then the characters on the second line and so on down the screen. In the attribute bytes, bits 0, 1 & 2 determine the INK colour, bits 3, 4 & 5 the PAPER colour, bit 6 is-set for BRIGHT and reset for normal, and bit 7 is set for FLASHing and reset for steady.

The printer buffer The locations between decimal 23,296 and 23,551, hex. 5BO0—5BFF, are used as a printer buffer.

15

These 256 bytes are sufficient to hold 32 characters in their high resolution form with the first 32 bytes holding the bits for the top line of the characters, the next 32 bytes the bits for the second line, and so on.

Note that the printed buffer can be used as a ‘work space’ if required.

The system variables

The 182 locations from decimal 23,552 to 23,733, hex. 5COO—5CB5, hold the many different system variables of the SPECTRUM system. These system variables will be discussed in detail as the need arises throughout the remainder of this book.

The microdrive maps

This area of the memory begins at location decimal 23,734, hex, 5CB6, and has only a theoretical existence in a standard SPECTRUM, that is to say that the area is not used unless a microdrive has been fitted.

As this book is being written before the appearance of microdrives it is not possible to discuss the microdrive maps any further. However, by making the system variable CHANS point further ‘up’ the available memory it is possible to reserve any amount of memory (within the limit of available RAM) for the microdrive maps. (The use of the microdrive map area as a place to keep user- written machine code is an interesting point.)

The channel information area

This special area of the memory starts at the location pointed to by the system variable CHANS -— itself stored in locations decimal 23,631 & 23,632, hex, 5C4F-5C50. The area is of variable size but ends with a location holding an end-marker of value decimal 128, hex. 80.

In the standard SPECTRUM, that is a machine without any microdrives attached, there are the input and output details for four channels. These channels are:

Channel ‘K’ which allows input from the keyboard and output to the lower part of the display.

Channel ‘S’ which does not allow any input but will allow output to go to the upper part of the display.

Channel ‘R’ which again will not allow any input but will allow output to be passed to the work space. The size of the work space is expanded as required.

Channel ‘P’ which again will not allow any input but will allow out- put to go to the printer.

The channel information consists, for each channel, of five bytes of data. These bytes are the output routine address which takes two bytes, the input

16

routine address which also takes two bytes and the file name which is a single letter code.

As there are four channels and an end-marker, the channel information area in a standard SPECTRUM occupies the twenty one locations from decimal 23,734 to 23,754, hex. 5CB6-5CCA.

The BASIC program area This area of the memory holds the current program lines, if any. The size of the area depends on just how many BASIC lines exist.

The start of the program area is always given by the value held in the system variable PROG, which itself occupies the locations decimal 23,635 & 23,636, hex. 5C53-5C54,

Note that in the standard SPECTRUM the system variable PROG will indicate that the BASIC program starts at location decimal 23,755, hex. 5CCB, and this will always be so unless the microdrive map area is being used, or extra locations have been reserved for additional channel information.

In the program area BASIC lines are stored in the following format: The first two bytes of any line hold the line number with the first byte being the ‘high’ byte and the second byte being the ‘low’ byte. The third and fourth bytes of a line hold the ‘remaining length’. This time the ‘low’ byte comes before the ‘high’ byte. The ‘remaining length’ is the number of bytes from the fifth byte to the final ENTER character in- clusively. Now comes the BASIC line itself. Sinclair codes are used for the tokens and some characters and ASCII codes for the standard alphanumeric characters. The last byte of a line is always an ENTER character. Within a BASIC line multiple statements are separated from each other by colons character decimal 58, hex. 3A. There are no further markers for multiple statements. Note that if a decimal number occurs in a BASIC line then it is stored as its ASCII characters and followed by the NUMBER character decimal 14, hex. OE, and the floating-point form for the number, or the integer form for integers in the range —65,535 to +65,535, which in either case will take a further five bytes. This leads to there being six extra bytes of RAM being used for every decimal number that is in- cluded in a BASIC program.

The following demonstration program ‘looks at itself’ in the program area and shows the above points.

PROGRAM AREA DEMONSTRATION PROGRAM

18 FOR A=23755 LO 23817: PRINT

A;TAB 9;PEEK A;TAB 15;CHRY PEEK

A: NEXT A

RUN

7

The variables area

The starting location of this area that holds the current BASIC variables is always given by the value held in the system variable VARS, which itself occupies the locations decimal 23,627 & 23,628, hex. 5C4B-5C4C.

Note that in the SPECTRUM system the start of the variables will not change during the execution of any given BASIC program. Its size will how- ever change as new variables are defined.

The fast location in the variables area always contains the end-marker character decirnal 128, hex, 80.

The following program looks at its own variables area which contains only the control variable for the FOR-NEXT loop.

VARIABLES AREA DEMONSTRATION PROGRAM:

1g FOR A=23804 TO 23823: PRINT A;TAB 9;PEEK A; NEXT A RUN

The editing area

The starting location of this area that holds the BASIC line being entered, or edited, is always given by the value held in the system variable E-LINE, which itself occupies the locations decimal 23,641 & 23,642, hex. 5C59-5C5A. When the lower part of the T.V. display shows only the flashing cursor the editing area will have three locations allocated to it. The first location, whose address is also held by the systems variable K—CUR, holds an ENTER charac- ter, and the second location an end-marker again a character decimal 128, hex. 80. The lower part of the T.V. display is obtained by copying over the ‘edit-line’ and displaying it.

Then, as characters are entered from the keyboard the editing area is expanded to hold them.

A similar procedure occurs when the EDIT key is used to fetch a BASIC line to the lower part of the display. First of all the editing area is expanded to the correct extent to allow for the BASIC line. Then the line is copied over from the program area to the editing area and finally the line in the editing area is copied over to the lower part of the display RAM. This last stage does involve the forming of high resolution representations from the character codes.

As the editing area is a dynamic area, that is it changes whenever it is used, it is not practical to give an example in BASIC at this point.

18

' |

The work space This area of the memory is used for many different tasks, e.g. INPUT data, the concatenation of strings, etc. The starting location of the area is given by the value held in the system variable WORKSP, which itself occupies the loca- tions decimal 23,649 & 23,650, hex. 5C61-5C62. Whenever space is required in the work space this area of the memory is expanded. After use the work space is emptied, that is ‘collapsed to nothing’ so as to avoid using more locations than is absolutely necessary.

Once again as this area is dynamic it is not possible to give a simple BASIC example of its use.

The calculator stack This very important area of the memory starts at the location addressed by the system variable STKBOT, which itself occupies the locations 23,651 & 23,652, hex. 5C63-5C64, and extends to the location before that addressed by the system variable STKEND, which occupies the locations 23,653 & 23,654, hex. 5C65-5C66.

The calculator stack is used to hold floating-point numbers, five byte integers and when dealing with strings, five byte sets of string parameters.

The stack is manipulated on a ‘last-in first-out’ basis and the value held at the top of the stack can be considered, if one does exist, as a ‘last value’.

The spare memory

The area of memory between the calculator stack and the machine stack re- presents the amount of memory that is available to the user. In a standard 16K SPECTRUM there are nominally 8,839 locations in this area when the system is turned on. However it is interesting to note that the lowest accept- able value for CLEAR is 23,821 which pushes RAMTOP down by 8,878 bytes.

The machine stack The Z80 microprocessor has to have an area of work space for its own use and this is termed the machine stack. The stack pointer of the 780 always points to the last location to have been filled.

The machine stack will be considered in much greater detail in the machine code part of this book.

The GO SUB stack: Whenever there are any active GO SUB loops the looping line numbers are kept on the GO SUB stack.

The stack grows downwards in memory and each GO SUB looping address requires three locations. The highest location holds the number of the state-

19

ment within the BASIC line to where the return is to be made. The next loca- tion holds the ‘low’ part of the looping line number and the third location the ‘high’ part.

The following demonstration program shows the GO SUBstack being used to hold the looping line numbers for three nested subroutines.

GO SUB STACK DEMONSTRATION PROGRAM:

1@ GO SUB 2%: STOP

28 GO SUB 3%: RETURN

38 GO SUB 4@: RETURN

48 FOR A=32597 TO 32589 STEP —- 1: PRINT A,PEEK A: NEXT A: RETUR N

RUN

The two locations above the GO SUB stack always contain the values @ and 62, hex. 00 and 3E, and between them they represent an illegal line number. A BASIC program that contains an extra RETURN command will by attempting to make a jump to the illegal line cause the ‘RETURN without GOSUB’ error message to be printed. (Note: Sinclair is not totally consistent over the spelling of GO SUB.)

The system variable RAMTOP, which occupies the locations decimal 23,730 & 23,731, hex. 5CB2-5CB3, holds the address of the location that contains the value 62. This location is considered as being the last location in the BASIC system area.

The user-defined graphics area

Unless the BASIC system area has been moved down by the use of a CLEAR command, the top one hundred and sixty eight locations in the memory hold the bit representations of the 21 user-defined graphics.

As part of the initialization procedure of the SPECTRUM the bit repre- sentation of the latters A to U are copied to this area. Later on the user is able to change these representations to give up to 21 user-defined graphics.

The topmost location in the memory is always addressed by the system variable P-RAMT, which occupies the locations decimal 23,732 & 23,733, hex. 5CB4-5CB5.

20

In the standard 16K SPECTRUM the value held in P-RAMT ought to be 32,767 as this shows that all of the 16K of memory is in working order,

It certainly does no harm to occasionally enter the line:

PRINT PEEK 23732+256*PEEK 23733 and see that the result is indeed the value 32767. (In a 48K SPECTRUM the result should be 65535.)

21

2. UNDERSTANDING BASIC commands and functions

2.1 Introduction

It is expected that the readers of this book will already have acquired a reason- able knowledge of the SPECTRUM’S BASIC so this chapter discusses the BASIC commands and functions trying to bring out points that are not mentioned in detail in the two handbooks supplied with each SPECTRUM.

The BASIC interpreter of the SPECTRUM recognizes fifty different commands and thirty three functions. Each of these will now be discussed briefly. They will be dealt with in alphabetical order so as to make reference to them a little easier. The control characters are discussed in section 2.4.

2.2 The BASIC commands

BEEP xy This command causes a note to be produced by the loudspeaker. x is the duration in seconds and y the pitch of the note away from middle C, within the range decima! —60 to +69.8. Either x or y, or both, can be expressions.

It is interesting to note that a BEEP cannot be interrupted as the program of the BEEP command routine does not check the BREAK key. A BREAK is only possible at the end of the statement containing the BEEP command.

BORDER m

There are eight possible colours that can be given to the border area of the T.V. display. The integer range for m is thereby 0 to 7. However m is rounded and the true acceptable range is -0.5 <m <7.5. m can be an expression and is accepted as long as the result lies within the given range.

The effect of a BORDER m command is to send an OUT signal on port 254, and this can be shown by trying the line

OUT 254, m (where m=2 will give a red border).

But OUT and BORDER are different. The colour given to the border area by an OUT command is a ‘temporary’ colour, whereas a BORDER command gives a ‘permanent’ colour with the colour being stored in the system variable BORDGCR. (location decimal 23,624, hex. 5C48)

This permanence can be shown as follows:

Enter BORDER 2 & ENTER which will make the border area RED. Then enter OUT 254,1 & ENTER and the border will go BLUE but this is just temporary as a further ENTER will return the RED border. Note also how BORDCR keeps the colour of the paper in the lower part of the T.V. display.

22

BRIGHT m

This is the first of the ‘colour item’ commands. All of these commands can be used either as the only command in a BASIC statement, in which case the command is ‘permanent’, or embedded in a printing statement, in which case the command is ‘temporary’.

m can be an expression but only the integer results of O, 1 & 8 are accept- able.

With m=0 the display will be of normal brilliance but with m=1 any future printing will be done on BRIGHT paper. The use of BRIGHT 1 & CLS is the easiest way of making the whole screen display become BRIGHT.

With m=8 any printing to be done will use the brilliance for a character area that is already assigned.

The following lines show the four different ways in which a colour item, such as BRIGHT can be used.

1@ BRIGHT 1: PRINT “Bright—”;: BRIGHT @: PRINT “Normal” which on two occasions changes the brilliance in a ‘permanent’ manner. 20 PRINT BRIGHT 1; “Bright—”;B RIGHT @; “Normal” which changes the brilliance ‘temporarily’ during the statement. 30 PRINT CHR$ 19+CHRS 1; “Brigh t—, CHR$ 19+CHRS: @ “Normal” which replaces the command with its CHR equivalent. 49 LET AS=CHRS 19+CHRS 1: LET BS=CHR$ 19+CHR$ @: PRINT AS;"Bri ght—"; BS; “Normal” which puts the colour items into string variables.

It is also possible to use the keystrokes ‘extended, unshifted 9’ for BRIGHT 1, and ‘extended, unshifted 8’ for BRIGHT 0. These keystrokes may be placed inside a quote area, ie. between the open-quote and the first character, or quite advantageously in string variables to be used as required, e.g. LET AS’: REM Inside the quotes is an extended unshifted 9. Printing Ag will then act as BRIGHT 1.

CAT For use with microdrives. (No details available yet) CIRCLE x,y,z This command draws a circle of radius z, with x & y giving the centre.

zis taken as an absolute integer, whereas x & y are manipulated as floating- point numbers.

The largest circle that can be drawn is of radius 88 units as with the line CIRCLE 127.5,87.5,88 whereas a ‘circle’ with radius zero is a single point. Any of the ‘colour item’ commands may be embedded inside a CIRCLE statement and their effect will always be ‘temporary’.

23

By some standards the CIRCLE command is rather slow and inaccurate but nevertheless it is very useful.

CLEAR and CLEAR n

As the SPECTRUM system has such a large amount of RAM available to the user, the use of a CLEAR command by itself is unlikely to be very helpful. However, the extension of the command to include a facility for moving RAMTOP makes it a powerful command. RAMTOP is the pointer to the top of the BASIC system and the contents of any location below RAMTOP is liable to be overwritten and thereby destroyed, whereas any locations above RAMTOP are safe even from a NEW command.

The lower limit for n that is possible is 23,821 after which the SPECTRUM will buzz when a key is pressed. This shows that there is insufficient RAM available for the task.

The upper limit for n is, for a 16K system 32,767, and for 48K system 65,535. The use of CLEAR n with the appropriate number has the effect of putting the machine and GO SUB stacks in the area used for user-defined graphics. It is instructive to try the following steps as it is possible to see, indirectly, the contents of the stacks changing as they are used.

Enter CLEAR 32767 (or 65535).

Change the cursor to G and enter the letters L to U. Then hold down the SPACE key for several seconds and watch the user-defined graphics changing as each key press leads to the machine stack being used.

CLOSE For use with microdrives.

CLs An apparently very simple command which takes less than a tenth of a second to execute but it does involve the microprocessor in a lot of work, The CLS command clears the display file. In effect it writes zeroes into all the locations from decimal 16,384 to 22,527, hex. 4000-5800, and resets all the attribute bytes in locations 22,528 to 23,295, hex. 5800-5AFF. The command does not set these latter locations to zero but rather copies the system variable ATTR-P into each location. ATTR-P, which is surely the abbreviation of ‘permanent attribute’ holds the current permanent attributes. By POKEing different values into ATTR-P at location decimal 23,693, hex. 5C8D, and then pressing ENTER an extra time, it will be seen that the screen changes predictably. In ATTR-P, bit 7 controls the FLASH, bit 6 the BRIGHTnhness, bits 3-5 the PAPER colour and bits 0-2 the INK colour.

24

CONTINUE

In most of the required instances this command works well. But when dealing with direct commands the user may find that the computer goes into a ‘loop’ that can be exited only be resorting to the BREAK key.

There are two distinct facets to the CONTINUE command. The first is to allow the user to have STOP statements in a BASIC program which may be stepped over by using the CONT key. The same operation works in respect to using the BREAK key. In this type of operation the user is able to examine variables, set variables and change the BASIC program in any way, except for deleting the STOP statement. The use of a STOP statement and the CON- TINUE command can be very helpful when de-bugging programs.

The second facet allows the user to repeat the interpretation of a state- ment after correcting an error. For example it a program stops with a ‘vari- able not found’ error then the variable can be defined using a direct command and the program restarted using a CONTINUE command.

Six system variables NEWPPC, NSPPC, PPC, SUBPPC, OLDPPC and OSPCC are involved in some way with the execution of the CONTINUE command and the details are given in Chapter 25 of ‘BASIC programming’.

coPy

This is a very straighforward command. Unless the printer is not attached to the SPECTRUM, the top 22 lines of the T.V. display are sent to the printer. The one hundred and seventy six high resolution lines of the T.V. display area are dealt with in turn. The COPY command is one of several commands that switch off the ‘real time clock’ and hence the clock loses time if COPY is used. This can be shown by examining the system variable FRAMES before and after the use of COPY.

DATAe,e,...

This command, which can only be used in a program line, sets up a data list. Although it is mentioned in the manual, it is not made very clear that the items in a DATA statement are dealt with as expressions a feature that does make this command very useful. For further details see READ & RESTORE.

DEF FNata,...z}=e & DEF FN a${a,...z/-e The DEF FN command is very powerful in the SPECTRUM.

The user is able to define up to 52 functions 26 numeric and 26 string. The names used for the functions must always be single characters (+$ for strings) and they can be names that are used elsewhere as simple variables.

There is a slight restriction on the names of the arguments that can be used as these must also be single characters (+% for strings). Therefore again up to

25

52 arguments are possible should they be needed. The expression of a defined function can be anything that gives the appropriate numeric or string result. However including the function itself as a defined function in the expres- sion does lead to confusion {to date the only way the author knows to ‘crash’ the SPECTRUM in BASIC.)

DiM aley,.. .@¢) & DIM aSfe,,. ey)

The DIM command ‘reclaims’ any existing array with the same name and then sets up a new array as directed. Numeric arrays have zero in every location, whilst in string arrays ‘space’ characters are used.

In the SPECTRUM system all subscripts start as ‘1’, or more strictly 0.5< e <1.5. The common error of having a subscript reaching zero gives the ‘subscript wrong’ message. The use in the SPECTRUM system of fixed- length strings in string arrays, whereas simple string variables are of changing length, does lead