Appendix C: A description of the ZX Spectrum / The BASIC

Appendix C

Part 1: A description of the ZX Spectrum for reference

In the original paper version of this manual, the first section of this appendix was a repeat of that part of Chapter 1 concerning the keyboard and display.

The display window

Each character position has attributes specifying its paper (background) and ink (foreground) colours, a two-level brightness, and whether it flashes or not. The available colours are black, blue, red, magenta, green, yellow and white.

The edge of the screen can be set to any of the colours using the border statement.

A character position is divided into 8×8 pixels and high resolution graphics are obtained by setting the pixels individually to show either the ink or paper colour for that character position.

The attributes at a character position are adjusted whenever a character is written there or a pixel is plotted. The exact manner of the adjustment is determined by the pnnting parameters. of which there are two sets (called permanent and temporary) of six: the PAPER, INK, FLASH, BRIGHT, INVERSE and OVER parameters. Permanent parameters for the top part are set up by PAPER, INK, etc, statements, and last until further notice. (Initially they are black ink on white paper with normal brightness, no flashing, normal video and no overprinting). Permanent parameters for the bottom part use the border colour as the paper colour, with a black or white contrasting ink colour, normal brightness, no flashing, normal video and no overprinting.

Temporary parameters are set up by PAPER, INK, etc, items, which are embedded in PRINT, LPRINT, INPUT, PLOT, DRAW and CIRCLE statements, and also by PAPER, INK, etc control characters when they are printed to the television - they are followed by a further byte to specify the parameter value. Temporary parameters last only to the end of the PRINT (or whatever) statement, or, in INPUT statements, until some INPUT data is needed from the keyboard, when they are replaced by the permanent parameters.

PAPER and INK parameters are in the range 0 to 9. Parameters 0 to 7 are the colours used when a character is printed:

0	Black
1	Blue
2	Red
3	Magenta
4	Green
5	Cyan
6	Yellow
7	White

Parameter 8 ('transparent') specifies that the colour on the screen is to be left unchanged when a character is printed.

Parameter 9 ('contrast') specifies that the colour in question (paper or ink) is to be made either white or black to show up against the other colour.

FLASH and BRIGHT parameters are 0, 1 or 8: 1 means that flashing or brightness is turned on, 0 that it is turned off, and 8 ('transparent') that it is left unchanged at any character position.

OVER and INVERSE parameters are 0 or 1:

OVER 0 new characters obliterate old ones
OVER 1 the bit patterns of the old and new characters are combined using an 'exclusive or' operation (overprinting)
INVERSE 0 new characters are printed as ink colour on paper colour (normal video)
INVERSE 1 new characters are printed as paper colour on ink colour (inverse video)

When a TAB control character is received by the television, two more bytes are expected to specify a tab stop n (less significant byte first). This is reduced modulo 32 to n₀ (say), and then sufficient spaces are printed to move the printing position into column n₀. When a comma control character is received, then sufficient spaces (at least one) are printed to move the printing position into column 0 or column 16. When an Enter control character is received, the printing position is moved on to the next line.

The printer

Output to the ZX printer is via a buffer one line (32 characters) long, and a line is sent to the printer

1. when printing spills over from one line to the next,
2. when an Enter character is received,
3. at the end of the program, if there is anything left unprinted,
4. when a TAB control or comma control moves the printing position on to a new line.

TAB controls and comma controls output spaces in the same way as on the television.

The AT control changes the printing position using the column number, and ignores the line number.

The printer is affected by INVERSE and OVER controls (and also statements) in the same way as the screen is, but not by PAPER, INK, FLASH or BRIGHT.

The printer will stop with error B if Esc is pressed. If the printer is absent the output will simply be lost.

Part 2: The BASIC

Numbers are stored to an accuracy of 9 or 10 digits. The largest number you can get is about 10³⁸, and the smallest (positive) number is about 4×10^-39.

A number is stored in floating point binary with one exponent byte e (1≤e≤255), and four mantissa bytes m (1/2≤m<1). This represents the number m×2e^-128.

Since 1/2≤m<1, the most significant bit of the mantissa m is always 1. Therefore in actual fact we can replace it with a bit to show the sign - 0 for positive numbers, 1 for negative.

Small integers have a special representation in which the first byte is 0, the second is a sign byte (0 or FFh) and the third and fourth are the integer in twos complement form, the less significant byte first.

Numeric variables have names of arbitrary length, starting with a letter and continuing with letters and digits. Spaces and colour controls are ignored and all letters are converted to lower-case letters.

Control variables of FOR-NEXT loops have names a single letter long.

Numeric arrays have names a single letter long, which may be the same as the name of a simple variable. They may have arbitrarily many dimensions of arbitrary size. Subscripts start at 1.

Strings are completely flexible in length. The name of a string consists of a single letter followed by $.

String arrays can have arbitrarily many dimensions of arbitrary size. The name is a single letter followed by $ and may not be the same as the name of a string. All the strings in a given array have the same fixed length, which is specified as an extra, final dimension in the DIM statement. Subscripts start at 1.

Slicing: Substrings of strings may be specified using slicers. A slicer can be

1. empty or
2. numerical expression or
3. optional numerical expression TO optional numerical expression

and is used in expressing a substring either by

(a) string expression (slicer)
(b) string array variable (subscript,..., subscript, slicer)
which means the same as
string array variable (subscript . . . , subscript) (slicer)

In (a), suppose the string expression has the value s$.

If the slicer is empty, the result is s$ considered as a substring of itself.

If the slicer is a numerical expression with value m, then the result is the mth character of s$ (a substring of length 1).

If the slicer has the form (iii), then suppose the first numerical expression has the value m (the default value is 1), and the second, n (the default value is the length of s$).

If 1≤m≤n≤the length of s$ then the result is the substring of s$ starting with the mth character and ending with the nth. If 0≤n<m then the result is the empty string. Otherwise, error 3 results.

Slicing is performed before functions or operations are evaluated, unless brackets dictate otherwise.

Substrings can be assigned to (see LET).

If a string quote is to be written in a string literal, then it must be doubled.

Functions

The argument of a function does not need brackets if it is a constant or a (possibly subscripted or sliced) variable.

ABS	Gives the absolute magnitude of a numeric-expression.
ACS	Gives the arc-cosine of a numeric expression.
AND	Logical conjunction.
ASN	Gives the arc-sine of a numeric expression.
AT	Moves the print position to a point on the screen.
ATN	Gives the arc-tangent of a numeric expression.
ATTR	Gives the number whose binary form codes the attributes of a line.
BIN	Binary representation.
CHR$	Gives the character whose code is a given integer.
CODE	Gives the code of the first character in a string.
COS	Gives the cosine of a numeric expression.
EXP	Gives the value of e to a given power.
FN	Gives the return value from a user-defined function.
IN	Gives the result from inputting at processor level from a port.
INKEY$	Reads the keyboard.
INT	Gives the integer part of a numeric expression.
LEN	Gives the length of a string expression.
LN	Gives the natural logarithm (to base e) of a numeric expression.
NOT	Logical inversion.
OR	Logical disjunction.
PEEK	Gives the value of a byte in memory.
PI	Gives the value of the constant π.
POINT	Determines whether a pixel is ink colour or paper colour.
RND	Gives the next pseudo-random number in a sequence.
SCREEN$	Gives the character that appears on the screen at the given position.
SGN	Gives the sign of a numeric expression.
SIN	Gives the sine of a numeric expression.
SQR	Gives the square root of a numeric expression.
STR$	Gives the string of characters that would be displayed if a numeric expression were printed.
TAB	Shift the print position to a column on the current line.
TAN	Gives the tangent of a numeric expression.
USR	Calls a machine code subroutine, or gives the address of the first bit pattern for a user-defined graphic.
VAL	Gives the value of a string expression evaluated as a numeric expression.
VAL$	Gives the value of a string expression evaluated as a numeric expression and converted back to a string.

The following are binary operations:

+	Addition (on numbers), or concatenation (on strings)
-	Subtraction
*	Multiplication
/	Division
↑	Raising to a power. Error B if the left operand is negative
=	Equals
>	Greater than	Both operands must be of the same type. The result is a number: 1 if the comparison holds and 0 if it does not
<	Less than
<=	Less than or equal to
>=	Greater than or equal to
<>	Not equal to

Functions and operations have the following priorities:

Operation	Priority
Subscripting and slicing	12
All functions except NOT and unary minus	11
↑	10
Unary minus (i.e. minus just used to negate something)	10
*, /	8
+, - (minus used to subtract one number from another)	6
=, >, <, <=, >=, <>	5
NOT	4
AND	3
OR	2

Statements

Note that arbitrary expressions are allowed everywhere (except for the line number at the beginning of a statement).

All statements can be used either as commands or in programs (although they can be more sensible in one than the other). A command or program line can have several statements, separated by colons (:). There is no restriction on whereabouts in a line any particular statement can occur - although see IF and REM.

BEEP	Sounds a note through the loudspeaker.
BORDER	Sets the colour of the border of the screen.
BRIGHT	Sets brightness of characters subsequently printed.
CAT	Microdrive file handling command.
CIRCLE	Draws an arc of a circle.
CLEAR	Deletes all variables, freeing the space they occupied.
CLOSE #	Microdrive file handling command.
CLS	Clears the display file.
CONTINUE	Continues the program, starting where it left off last time it stopped.
COPY	Sends a copy of the top 22 lines of display to the printer.
DATA	Part of the DATA list.
DEF FN	User-defined function definition.
DIM	Sets up an array with specified dimensions.
DRAW	Draws a line from the current plot position.
ERASE	Microdrive file handling command.
FLASH	Defines whether characters will be flashing or steady.
FOR	Sets up a FOR-NEXT loop.
FORMAT	Microdrive file handling command.
GO SUB	Jumps to a subroutine.
GO TO	Jumps to a line.
IF	Conditional execution.
INK	Sets the ink colour of characters subsequently printed.
INPUT	Waits for input of an expression from the keyboard.
INVERSE	Controls inversion of characters subsequently printed.
LET	Assigns the value of an expression to a variable.
LINE	Removes quotes on string variable INPUTs, Autostarts saved programs.
LIST	Lists the program to the upper part of the screen.
LLIST	Lists the program to the printer.
LOAD	Loads a program or data.
LPRINT	Outputs characters to the printer.
MERGE	Loads a program and merges it with the existing one.
MOVE	Microdrive file handling command.
NEW	Starts the BASIC system off anew, deleting program and variables.
NEXT	Continues a FOR-NEXT loop.
OPEN #	Microdrive file handling command.
OUT	Outputs a byte at a port at the processor level.
OVER	Controls overprinting for characters subsequently printed.
PAPER	Sets the paper colour of characters subsequently printed.
PAUSE	Stops computing for the specified number of frames or until a key is pressed.
PLOT	Prints an ink spot at a pixel.
POKE	Writes a value to the byte in memory.
PRINT	Outputs characters to the screen.
RANDOMIZE	Seeds the random number generator.
READ	Assigns to variables using successive expressions in the DATA list.
REM	No effect.
RESTORE	Restores the DATA pointer to the first DATA statement.
RETURN	Returns from a subroutine.
RUN	Runs the program.
SAVE	Saves a program or data.
STOP	Stops the program with report 9.
TAB	Stops the program with report 9.
THEN	Separates an IF condition from the code to be executed.
TO	Denotes the limit of a FOR statement, and a string slicer.
VERIFY	Compares a saved program with the one in memory.

Appendix B