Concepts

The Concept Reference Guide describes concepts relating to SuperBASIC and the QL hardware. It is best to think of the Concept Guide as a source of information. If there are any questions about SuperBASIC or the QL itself which arise out of using the computer or other sections of the manual then the Concept Guide may have the answer. Concepts are listed in alphabetical order using the most likely term for that concept. If the subject cannot be found then consult the index which should be able to tell you which page to turn to.

Where an example is listed with line numbers, then it is a complete program and can be entered and run. Examples listed without numbers are usually simple commands and it may not always be sensible to enter them into the computer in isolation. Examples which demonstrate stipples will not work properly on a television set.

by Stephen Berry (Sinclair Research Limited)

Index

Character Set And Keys

Clock

Coercion

Colour

Communications - RS-232-C

Functions and Procedures

Pixel Coordinate System

String Arrays and String Variables

Arrays

Arrays must be DIMensioned before they are used. When an array is dimensioned the value of each of its elements is set to zero or a zero length string if it is a string array. An array dimension runs from zero up to the specified value. There is no limits to the number of dimensions which can be defined other than the total memory capacity of the computer. An array of data is stored such that the last index defined cycles round most rapidly:

Example:

the array defined by

DIM array(2,4)

will be stored as

0,0 low address

0,1

0,2

0,3

0,4

1,0

1,1

1,2

1,3

1,4

2,0

2,1

2,2

2,3

2,4 high address

The element referred to by array(a,b,c) is equivalent to the element referred to by array(a)(b)(c)

Command	Function

DIM	dimension an array
DIMN	find out about the dimensions of an array

BASIC

SuperBASIC includes most of the functions, procedures and constructs found in other dialects of BASIC. Many of these functions are superfluous in SuperBASIC but are included for compatibility reasons:


GOTO	use IF, REPEAT, etc
GOSUB	use DEFine PROCedure
ON...GOTO	use SELect
ON...GOSUB	use SELect

Some commands appear not to be present. They can always be obtained by using a more general function. For example, there are no LPRINT or LLIST statements in SuperBASIC but output can be directed to a printer by opening the relevant channel and using PRINT or LIST.


LPRINT	use PRINT #
LLIST	use LIST #
VAL	not required in SuperBASIC
STR$	not required in SuperBASIC
IN	not applicable to 68008 processor
OUT	not applicable to 68008 processor

comment

Almost all forms of BASIC require the VAL(x$) and STR$(x) functions in order to be able to convert the internal codified form of the value of a string expression to or from the internal codified form of the value of a numeric expression.

These functions are redundant in SuperBASIC because of the provision of a unique facility referred to as "coercion". The VAL and STR$ functions are therefore not provided.

Break

If at any time the computer fails to respond or you wish to stop a SuperBASIC program or command then

hold down

CTRL

and then press

SPACE

A program broken into in this way can be restarted by using the CONTINUE command.

Channels

A channel is a means by which data can be output to or input from a QL device. Before a channel can be used it must first be activated (or opened) with the OPEN command. Certain channels should always be kept open: these are the default channels and allow simple communication with the QL via the keyboard and screen. When a channel is no longer in use it can be deactivated (closed) with the CLOSE command.

A channel is identified by a channel number. A channel number is a numeric expression preceded by a #. When the channel is opened a device is linked to a channel number and the channel is initialised. Thereafter the channel is identified only by its channel number. For example:

OPEN #5,SER1

Will link serial port 1 to the channel number 5. When a channel is closed only the channel number need be specified. For example:

CLOSE #5

Opening a channel requires that the device driver for that channel be activated. Usually there is more than one way in which the device driver can be activated, for example the network requires a station number. This extra information is appended to the device name and passed to the OPEN command as a parameter. See concepts device and peripheral expansion.

Data can be output to a channel by PRINTing to that channel; this is the same mechanism by which output appears on the QL screen. PRINT without a parameter outputs to the default channel #1. For example:

10 OPEN #5,mdv1_test_file

20 PRINT #5,"this text is in file test_file"

30 CLOSE #5

will output the text "this text is in file test_file" to the file test_file. It is important to close the file after all the accesses have been completed to ensure that all the data is written.

Data can be input from a file in an analogous way using INPUT. Data can be input from a channel a character at a time using INKEY$

A channel can be opened as a console channel; output is directed to a specified window on the QL screen and input is taken from the QL keyboard. When a console channel is opened the size and shape of the initial window is specified. If more than one console channel is active then it is possible for more than one channel to be requesting input at the same time. In this case, the required channel can

be selected by pressing CTRL C to cycle round the waiting channels. The cursor in the window of the selected channel will flash.

The QL has three default channels which are opened automatically. Each of these channels is linked to a window on the QL screen.

channel 0 - command and error channel

channel 1 - output and graphics channel

channel 2 - program listing channel

Monitor Television


Command	Function


OPEN	open a channel for I/O
CLOSE	close a previously opened channel
PRINT	output to a channel
INPUT	input from a channel
INKEY$	input a character from a channel

Character set and keys

The cursor controls are not built in to the operating system: however, if these functions are to be provided by applications software, they should use the keys specified; also the specified keys should not normally be used for any other purpose.


Decimal	Hex	Keying	Display/Function

0	00	CTRL £	NULL
1	01	CTRL A
2	02	CTRL B
3	03	CTRL C	Change input channel (see note)
4	04	CTRL D
5	05	CTRL E
6	06	CTRL F
7	07	CTRL G
8	08	CTRL H
9	09	TAB (CTRL I)	Next field
10	0A	ENTER (CTRL J)	New line / Command entry
11	0B	CTRL K
12	0C	CTRL L
13	0D	CTRL M	Enter
14	0E	CTRL N
15	0F	CTRL O

16	10	CTRL P
17	11	CTRL Q
18	12	CTRL R
19	13	CTRL S
20	14	CTRL T
21	15	CTRL U
22	16	CTRL V
23	17	CTRL W
24	18	CTRL X
25	19	CTRL Y
26	1A	CTRL Z
27	1B	ESC (CTRL SHIFT \|)	Abort current level of command
28	1C	CTRL SHIFT \
29	1D	CTRL SHIFT ]
30	1E	CTRL SHIFT ´
31	1F	CTRL SHIFT ESC

32	20	SPACE
33	21	SHIFT 1	!
34	22	SHIFT '	"
35	23	SHIFT 3	#
36	24	SHIFT 4	$
37	25	SHIFT 5	%
38	26	SHIFT 7	&
39	27	'	'
40	28	SHIFT 9	(
41	29	SHIFT 0	)
42	2A	SHIFT 8	*
43	2B	SHIFT =	+
44	2C	,	,
45	2D	-	-
46	2E	.	.
47	2F	/	/

48	30	0	0
49	31	1	1
50	32	2	2
51	33	3	3
52	34	4	4
53	35	5	5
54	36	6	6
55	37	7	7
56	38	8	8
57	39	9	9
58	3A	SHIFT ;	:
59	3B	;	;
60	3C	SHIFT ,	<
61	3D	=	=
62	3E	SHIFT .	>
63	3F	SHIFT /	?

64	40	SHIFT 2	@
65	41	SHIFT A	A
66	42	SHIFT B	B
67	43	SHIFT C	C
68	44	SHIFT D	D
69	45	SHIFT E	E
70	46	SHIFT F	F
71	47	SHIFT G	G
72	48	SHIFT H	H
73	49	SHIFT I	I
74	4A	SHIFT J	J
75	4B	SHIFT K	K
76	4C	SHIFT L	L
77	4D	SHIFT M	M
78	4E	SHIFT N	N
79	4F	SHIFT O	O

80	50	SHIFT P	P
81	51	SHIFT Q	Q
82	52	SHIFT R	R
83	53	SHIFT S	S
84	54	SHIFT T	T
85	55	SHIFT U	U
86	56	SHIFT V	V
87	57	SHIFT W	W
88	58	SHIFT X	X
89	59	SHIFT Y	Y
90	5A	SHIFT Z	Z
91	5B	[	[
92	5C	\	\
93	5D	]	]
94	5E	SHIFT 6	^
95	5F	SHIFT -	_

96	60	£	£
97	61	A	a
98	62	B	b
99	63	C	c
100	64	D	d
101	65	E	e
102	66	F	f
103	67	G	g
104	68	H	h
105	69	I	i
106	6A	J	j
107	6B	K	k
108	6C	L	l
109	6D	M	m
110	6E	N	n
111	6F	O	o

112	70	P	p
113	71	Q	q
114	72	R	r
115	73	S	s
116	74	T	t
117	75	U	u
118	76	V	v
119	77	W	w
120	78	X	x
121	79	Y	y
122	7A	Z	z
123	7B	SHIFT [	{
124	7C	SHIFT \	\|
125	7D	SHIFT ]	}
126	7E	SHIFT ´	~
127	7F	SHIFT ESC	©

128	80	CTRL ESC	ä
129	81	CTRL SHIFT 1	ã
130	82	CTRL SHIFT '	â
131	83	CTRL SHIFT 3	é
132	84	CTRL SHIFT 4	ö
133	85	CTRL SHIFT 5	õ
134	86	CTRL SHIFT 7	ø
135	87	CTRL '	ü
136	88	CTRL SHIFT 9	ç
137	89	CTRL SHIFT 0	ñ
138	8A	CTRL SHIFT 8	æ
139	8B	CTRL SHIFT =	œ
140	8C	CTRL ,	á
141	8D	CTRL _	à
142	8E	CTRL .	â
143	8F	CTRL /	ë

144	90	CTRL 0	è
145	91	CTRL 1	ê
146	92	CTRL 2	ï
147	93	CTRL 3	í
148	94	CTRL 4	ì
149	95	CTRL 5	î
150	96	CTRL 6	ó
151	97	CTRL 7	ò
152	98	CTRL 8	ô
153	99	CTRL 9	ú
154	9A	CTRL SHIFT ;	ù
155	9B	CTRL ;	û
156	9C	CTRL SHIFT ,	ß
157	9D	CTRL =	¢
158	9E	CTRL SHIFT .	¥
159	9F	CTRL SHIFT /	`

160	A0	CTRL SHIFT 2	Ä
161	A1	CTRL SHIFT A	Ã
162	A2	CTRL SHIFT B	Â
163	A3	CTRL SHIFT C	É
164	A4	CTRL SHIFT D	Ö
165	A5	CTRL SHIFT E	Õ
166	A6	CTRL SHIFT F
167	A7	CTRL SHIFT G	Ü
168	A8	CTRL SHIFT H	Ç
169	A9	CTRL SHIFT I
170	AA	CTRL SHIFT J	Æ
171	AB	CTRL SHIFT K	Œ
172	AC	CTRL SHIFT L	α
173	AD	CTRL SHIFT M	δ
174	AE	CTRL SHIFT N	θ
175	AF	CTRL SHIFT O	λ

176	B0	CTRL SHIFT P	μ
177	B1	CTRL SHIFT Q	π
178	B2	CTRL SHIFT R	Φ
179	B3	CTRL SHIFT S	i
180	B4	CTRL SHIFT T	¿
181	B5	CTRL SHIFT U	Ƨ
182	B6	CTRL SHIFT V	§
183	B7	CTRL SHIFT W	¤
184	B8	CTRL SHIFT X	«
185	B9	CTRL SHIFT Y	»
186	BA	CTRL SHIFT Z	°
187	BB	CTRL [	÷
188	BC	CTRL \	←
189	BD	CTRL ]	→
190	BE	CTRL SHIFT 6	↑
191	BF	CTRL SHIFT _	↓

192	C0	Left	Cursor left one character
193	C1	ALT Left	Cursor to start of line
194	C2	CTRL Left	Delete left one character
195	C3	CTRL ALT Left	Delete line
196	C4	SHIFT Left	Cursor left one word
197	C5	SHIFT ALT Left	Pan left
198	C6	SHIFT CTRL Left	Delete left one word
199	C7	SHIFT CTRL ALT Left
200	C8	Right	Cursor right one character
201	C9	ALT Right	Cursor to end of line
202	CA	CTRL Right	Delete character under cursor
203	CB	CTRL ALT Right	Delete to end of line
204	CC	SHIFT Right	Cursor right one word
205	CD	SHIFT ALT Right	Pan right
206	CE	SHIFT CTRL Right	Delete word under & right of cursor
207	CF	SHIFT CTRL ALT Right

208	D0	Up	Cursor right
209	D1	ALT Up	Scroll up
210	D2	CTRL Up	Search backward
211	D3	ALT CTRL Up
212	D4	SHIFT Up	Top of screen
213	D5	SHIFT ALT Up
214	D6	SHIFT CTRL Up
215	D7	SHIFT CTRL ALT Up
216	D8	Down	Cursor down
217	D9	ALT Down	Scroll down
218	DA	CTRL Down	Search forwards
219	DB	ALT CTRL Down
220	DC	SHIFT Down	Bottom of screen
221	DD	SHIFT ALT Down
222	DE	SHIFT CTRL Down
223	DF	SHIFT CTRL ALT Down

224	E0	CAPS LOCK	Toggle CAPS LOCK function
225	E1	ALT CAPS LOCK
226	E2	CTRL CAPS LOCK
227	E3	ALT CTRL CAPS LOCK
228	E4	SHIFT CAPS LOCK
229	E5	SHIFT ALT CAPS LOCK
230	E6	SHIFT CTRL CAPS LOCK
231	E7	SHIFT CTRL ALT CAPS LOCK
232	E8	F1
233	E9	CTRL F1
234	EA	SHIFT F1
235	EB	CTRL SHIFT F1
236	EC	F2
237	ED	CTRL F2
238	EE	SHIFT F2
239	EF	CTRL SHIFT F2

240	F0	F3
241	F1	CTRL F3
242	F2	SHIFT F3
243	F3	CTRL SHIFT F3
244	F4	F4
245	F5	CTRL F4
246	F6	SHIFT F4
247	F7	CTRL SHIFT F4
248	F8	F5
249	F9	CTRL F5
250	FA	SHIFT F5
251	FB	CTRL SHIFT F5
252	FC	SHIFT space	"Special" space
253	FD	SHIFT TAB	Back tab (CTRL ignored)
254	FE	SHIFT ENTER	"Special" newline (CTRL ignored)
255	FF	See below

Codes up to 20 hex are either control characters or non-printing characters. Alternative keyings are shown in brackets after the main keying.

Note that CTRL-C is trapped by Qdos and cannot be detected without changes to the system variables.

Note that codes C0-DF are cursor control commands.

The ALT key depressed with any key combination other than cursor keys or CAPS LOCK generates the code FF, followed by a byte indicating what the keycode would have been if ALT had not been depressed.

Note that CAPS LOCK and CTRL-F5 are trapped by Qdos and cannot be detected without special software.

Clock

The QL contains a real time clock which runs when the computer is switched on.

The format used for the date and time is standard ISO format.

1983 JAN 01 12:09:10

Individual year, month, day and time can all be obtained by assigning the string returned by DATE to a string variable and slicing it. The clock will run from 1961 JAN 01 00:00:00

Comment:

For a description of the format, see BS5249: Part 1: 1976 and as modified in Appendix D.2.1 Table 5 Serial 5 and Appendix E.2 Table 6 Serials 1 and 2.

Command	Function
SDATE	set the clock
ADATE	adjust the clock
DATE	return the date as a number
DATE$	return the date as a string
DAY$	return day of the week

Coercion

If necessary SuperBASIC will convert the type of unsuitable data to a type which will allow the specified operation to proceed.

The operators used determine the conversion required. For example, if an operation requires a string parameter and a numeric parameter is supplied then SuperBASIC will first convert the parameter to type string. It is not always possible to convert data to the required form and if the data cannot be converted an error is reported.

The type of a function or procedure parameter can also be converted to the correct type. For example, the SuperBASIC LOAD command requires a parameter of type name but can accept a parameter of type string and which will be converted to the correct type by the procedure itself. Coercion of this form is always dependent on the way the function or procedure was implemented.

There is a natural ordering of data types on the QL, see figure below. String is the most general type since it can represent names, floating point and integer numbers. Floating point is not as general as string but is more general than integer since floating point data can represent integer (almost exactly). The figure below shows the ordering diagramatically. Data can always be converted moving up the diagram but it is not always possible moving down.

Example

a = b + c	(no conversion is necessary before performing the addition. Conversion is not necessary before assigning the result to a)

a% = b + c	(no conversion is necessary before performing the addition but the result is converted to integer before assigning)

a$ = b$ + c$	(b$ and c$ are converted to floating point, if possible, before being added together. The result is converted to string before assigning)

LOAD "mdv1_data"	(the string "mdv1_data" is converted to type name by the LOAD procedure before it is used)

Statements can be written in SuperBASIC which would generate errors in most other computer languages. In general, it is possible to mix data types in a very flexible manner:

i. PRINT "1" + 2 + "3"

ii. LET a$ = 1 + 2 + a$ + "4"

COLOUR

Colours on the QL can be either a solid colour or a stipple - a mixture of two colours to some predefined pattern. Colour specification on the QL can be up to three items: a colour, a contrast colour and a stipple pattern.

Single:

colour:= composite_colour

The single argument specifies the three parts of the colour specification. The main colour is contained in the bottom three bits of the colour byte. The next three bits contain the exclusive or (XOR) of the main colour and the contrast colour. The top two bits indicate the stipple pattern.

By specifying only the bottom three bits (i.e. the required colour) no stipple will be requested and a single solid colour will be used for display.

Double:

colour: = background, contrast

The colour is a stipple of the two specified colours. The default checkerboard stipple is assumed (stipple 3)

Triple:

colour: = background, contrast, stipple

Background and contrast colours and stipple are each defined separately.

Colours:

The codes for colour selection depend on the screen mode in use:

Code	bit pattern	composition			colour
					8 colour	4 colour
0	0 0 0				black	black
1	0 0 1			blue	blue	black
2	0 1 0		red		red	red
3	0 1 1		red +	blue	magenta	red
4	1 0 0	green			green	green
5	1 0 1	green +		blue	cyan	green
6	1 1 0	green +	red		yellow	white
7	1 1 1	green +	red +	blue	white	white

Colour Composition and Codes

Stipples

Stipples mix a background and a contrast colour in a fine stipple pattern. Stipples can be used on the QL in the same manner as ordinary solid colours although stipples may not be reproduced correctly on an ordinary domestic television. There are four stipple patterns:

Stipple 3 is the default.

Example:

i. PAPER 255 : CLS

ii. PAPER 2,4 : CLS

iii. PAPER 0,2,0 : CLS

Warning:

Stipples may not reproduce correctly on a domestic television set which is fed via the UHF socket.

COMMUNICATIONS RS-232-C

The QL has two serial ports (called SER1 and SER2) for connecting it to equipment which uses serial communications obeying EIA standard RS-232-C or a compatible standard.

The RS-232-C 'standard' was originally designed to enable computers to send and receive data via telephone lines using a modem. However, it is now frequently used to connect computers directly with each other and to various items of peripheral equipment, e.g. printers, plotters, etc.

As the RS-232-C 'standard' manifests itself in many different forms on different pieces of equipment, it can be an extremely difficult job, even for an expert to connect together for the first time two pieces of supposedly standard RS-232-C equipment. This section will attempt to cover most of the basic problems that you may encounter.

The RS-232-C 'standard' refers to two types of equipment:

1. Data Terminal Equipment (DTE)

2. Data Communication Equipment (DCE)

The standard envisaged that the terminal (usually the DTE) and the modem (usually the DCE) would both have the same type of connector.

The diagram above illustrates how the DTE transmits data on pin 2 whilst the DCE must receive data on its pin 2 (which is still called transmit data!). Likewise, the DTE receives data on pin 3 whilst the DCE must transmit data on its pin 3 (which is still called receive data!). Although this is confusing in itself, it can lead to far greater problems when there is disagreement as to whether a certain device should be configured as DCE or DTE.

Unfortunately, some people decide that their computers should be configured as DCE devices whilst others configure equivalent computers as DTE devices. This obviously leads to difficulties in the configuration of the serial ports on each piece of equipment.

SER1 on the QL is configured as DCE, while SER2 is configurd as DTE. Therefore, it should be possible to connect at least one of the serial ports to a given device simply by using whichever port is wired the 'correct' way. The pin-out for the serial ports is given below. A cable for connecting the QL to a standard 25-way 'D' type connector is available from Sinclair Research Limited.

SER1			SER2
pin	name	function	pin	name	function
1	GND	Signal ground	1	GND	Signal ground
2	TxD	Input	2	TxD	Output
3	RxD	Output	3	RxD	Input
4	DTR	Ready input	4	DTR	Ready output
5	CTS	Ready output	5	CTS	Ready input
6	-	+12V	6	-	+12V
TxD	Transmit Data		DTR	Data Terminal Ready
RxD	Receive Data		CTS	Clear To Send

Once the equipment has been connected to the 'correct' port, the baud rate (the speed of transmission of data) must be set so that the baud rates for both the QL and the connected equipment are the same. The QL can be set to operate at:

300

600

1200

2400

4800

9600

19200 (transmit only) baud

The QL baud rate is set by the BAUD command and is set for both channels. The baud rates cannot be set independently.

The parity to be used by the QL must also be set to match that expected by the peripheral equipment. Parity is usually used to detect simple transmission errors and may be set to be even, odd, mark, space or no parity, i.e. all 8 bits of the byte are used for data.

Stop bits mark the end of transmission of a byte or character. The QL will receive data with one, one and a half, or two stop bits, and will always transmit data with at least two stop bits. Note that if the QL is set up to 9600 baud it will not receive data with only one stop bit: at least one and a half stop bits are required.

The may be necessary to connect the handshake lines between the QL and a piece of equipment connected to it. This allows the QL and its peripheral to monitor and control their rate of communication. They may need to do this if one of them cannot cope with the speed at which data is being transmitted. The QL uses two handshaking lines:

CTS	Clear to Send
DTR	Terminal Ready

If DTE cannot cope with the rate of transmission of data then it can negate the DTR line which tells the DCE to stop sending data. Obviously, when the DTE has caught up it tells the DCE, via the DTR line, to start transmitting again. In the same way, the DCE can stop the DTE sending data by negating the CTS line. If additional control signals are required they can be wired up using the 12V supply available on both serial ports.

Although transmission from the QL is often possible without any handshaking at all, the QL will not receive correctly under any circumstances without the use of CTS on SER1 and DTR on SER2.

Communications on the QL are 'full duplex', that is both receive and transmit can operate concurrently.

The parity and handshaking are selected when the serial channel is opened.

command	function
BAUD	set transmission speed
OPEN	open serial channels *
CLOSE	close serial channels

* see concept 'DEVICE' for a full specification

DATA TYPES - VARIABLES

integer

Integers are whole numbers in the range -32768 to +32767. Variables are assumed to be integer if the variable identifier is suffixed with a percent %. There are no integer constants in SuperBASIC, so all constants are stored as floating point numbers.

syntax:	identifier%

example:	i.	counter%
	ii.	size_limit%
	iii.	this_is_an_integer_variable%

floating point

Floating point numbers are in the range +/- (10^-615 to 10⁺⁶¹⁵), with 8 signiflcant digits. Floating point is the default data type in SuperBASIC. All constants are held in floating point form and can be entered

using exponent notation.

syntax:	identifier \| constant

example:	i.	current_accumulation
	ii.	76.2356
	iii.	354E25

string

A string is a sequence of characters up to 32766 characters long. Variables are assumed to be type string if the variable name is suffixed by a $. String data is represented by enclosing the required characters in either single or double quotation marks.

syntax:	identifier$ \| "text"

example:	i.	string_variables$
	ii.	"this is string data"
	iii.	"this is another string"

name

Type name has the same form as a standard SuperBASIC identifier and is used by the name system to name Microdrive files etc.

syntax:	identifier

example:	i.	mdv1_data_file
	ii.	ser1e

DEVICES

A device is a piece of equipment on the QL to which data can be sent (input) and from which data can be output.

Since the system makes no assumptions about the ultimate I/O (input/output) device which will be used, the I/O device can be easily changed and the data diverted between devices. For example, a program may have to output to a printer at some point during its run. If the printer is not available then the output can be diverted to a Microdrive file and stored. The file can then be printed at a later date. I/O on the QL can be thought of as being written to and read from a logical file which is in a standard device-independent form.

All device specific operations are performed by individual device drivers specially written for each device on the QL. The system can automatically find and include drivers for peripheral devices which are fitted. These should be written in the standard QL device driver format; see the concept peripheral expansion.

When a device is activated a channel is opened and linked to the device. To correctly open a channel device basic information must sometimes be supplied. This extra information is appended to the device name.

The file name should conform to the rules for a SuperBASIC type name though it is also possible to build up the file name (device name) as a SuperBASIC string expression.

In summary the general form of a file name is:

identifier [information]

where the complete file name (including the extra information) conforms to the rules for a SuperBASIC identifier.

Each logical device on the system requires its own particular 'extra information' although default parameters will be assumed in each case where possible.

Define

device: = name

where the form of the device name is outlined below.

example

for console device

CON_wXhaxXy_k

Console I/O

[wXh]	- window width, height
[AxXy]	- window X,Y coordinate of upper left-hand corner
[k]	- keyboard type ahead buffer length (bytes)

default:	con_448x180a32x16_128

example:	OPEN #4,con_20x50a0x0_32
	OPEN #8,con_20x50
	OPEN #7,con_20x50a10x10

SCR_wXhaxXy

Screen Output

[wXh]	- window, width, height
[AxXy]	- window X, Y coordinate
default:	scr_448x180a32x16

example:	OPEN #4, scr _0x10a20x50
	OPEN #5, scr_10x10

SERnphz

Serial (RS-232-C)

n port number (1 or 2)
[p] parity	[h] handshaking	[z] protocol
e – even	i – ignore	r - raw data no EOF
o – odd	h – handshake	z - control Z is EOF
m – mark		c - as z but converts
s – space		ASCII 10 (Qdos
		newline character)
		to ASCII 13
		<CR>)

default:	ser1rh (8 bit no parity with handshake)

example:	OPEN #3, serle
	OPEN #4, serc
	COPY mdv1_test_file TO ser1c

NETd_s

Serial Network I/O

[d] indicates direction	[s] station number
i – input	0 - for broadcast
o – output	own station - for general listen (input only)

default:	no default

example:	OPEN #7, neti_32
	OPEN #4, neto_0
	COPY ser1 TO neto_21

MDVn_name

Microdrive File Access

n - Microdrive number

name - Microdrive file name

default:	no default

example:	OPEN #9, mdv1_data_file
	OPEN #9, mdv1_test_program
	COPY mdv1_test_file TO scr_

Keyword	Function

OPEN	initialise a device and activate it for use

CLOSE	deactivate a device

COPY	copy data between devices
COPY_N	copy data between devices, but do
	not copy a file's header information

EOF	test for end of file

WIDTH	set width

DIRECT COMMAND

SuperBASIC makes a distinction between a statement typed in preceded by a line number and a statement typed in without a line nurnber. Without a line number the statement is a direct command and is processed immediately by the SuperBASIC command interpreter. For example, RUN is typed in on the command line and is processed, the effect being that the program starts to run. If a statement is typed in with a line number then the syntax of the line is checked and any detectable syntax errors reported. A correct line is entered into the SuperBASIC program and stored. These statements constitute a SuperBASIC program and will only be executed when the program is started with the RUN or GOTO command.

Not alI SuperBASIC statements make sense when entered as a direct command, for example, END FOR, END DEFine, etc

ERROR HANDLING

Errors are reported by SuperBASIC in a standard form:

At line line_number error_text

Where the line number is the number of the line where the error was detected and the error text is listed below.

(1) Not complete

An operation has been prematurely terminated (or break has been pressed).

(2) Invalid job

An error return from Qdos relating to system calls controlling multitasking or I/O.

(3) Out of memory

Qdos and/or SuperBASIC has insufficient free memory.

(4) Out of range

Usually results from attempts to write outside a window or an incorrect array index.

(5) Buffer full

An I/O operation to fetch a buffer full of characters filled the buffer before a record terminator was found.

(6) Channel not open

Attempt to read, write or close a channel which has not been opened. Can also occur if an attempt to open a channel fails.

(7) Not found

File system, device, medium or file cannot be found. SuperBASIC cannot find an identifier. This can result from incorrectly nested structures.

(8) Already exists

The file system has found an already existing file with the same name as a new file to be opened for writing.

(9) In use

The file system has found that a file or device is already exclusively used.

(10) End of file

End of file detected during input.

(11) Drive full

A device has been filled (usually Microdrive).

(12) Bad name

The file system has recognised the name but there is a syntax or parameter value error. In SuperBASIC it means a name has been used out of context. For example, a variable has been used as a procedure.

(13) Xmit error

RS-232-C parity error

(14) Format failed

Attempted format operation has failed, the medium is possibly faulty (usually a Microdrive cartridge).

(15) Bad parameter

There is an error in the parameter list of a system or SuperBASIC procedure or function call. An attempt was made to read data from a write only device.

(16) Bad or changed medium

The medium (usually a Microdrive cartridge) is possibly faulty

(17) Error in expression

An error was detected while evaluating an expression.

(18) Overflow

Arithmetic overflow division by zero, square root of a negative number, etc.

(19) Not Implemented

(20) Read only

There has been an attempt to write data to a shared file.

(21) Bad line

A SuperBASIC syntax error has occurred.

(22) PROC/FN cleared

This is a message which is for information only and is not reporting an error. It is reporting that the program has been stopped and subsequently changed forcing SuperBASIC to reset its internal state to the outer program level and so losing any procedure environment which may have been in effect.

error recovery

After an error has occurred the program can be restarted at the nextstatement by typing

CONTINUE

If the error condition can be corrected, without changing the program, the program can be restarted at the statement which triggered the error. Type

RETRY

EXPRESSIONS

SuperBASIC expressions can be string, numeric, logical or a mixture: unsuitable data types are automatically converted to a suitable form by the system wherever this is possible.

define

monop: =	\| +
	\| -
	\| NOT

expression: =	\| [monop] expression operator expression
	\| (expression)
	\| atom

	atom: =	\| variable
		\| constant
		\| function \| (expression \|, expression )
		\| array_element

		variable: =	\| identifier
			\| identifier %
			\| identifier $

		function: =	\| identifier
			\| identifier %
			\| identifier $

		constant: =	\| digit * [digit] *
			\| [digit] , [digit]
			\| [digit] \|,\| [digit] E [digit]

The final value returned by the evaluation of the expression can be integer giving an integer_expression, string giving a string_expression or floating point giving a floating expression. Often floating point and integer expressions are equivalent and the term numeric_expression is then used.

Logical operators can be included in an expression. If the specified operation is true then a one is returned as the value of the operation. If the operation is false then a zero is returned. Though logical operators can be used in any expression they are usually used in the expression part of an IF statement.

example:	i. test_data + 23.3 + 5
	ii. "abcdefghijklmnopqrstuvwxyz"(2 TO 4)
	iii. 32.1 * (colour = 1)
	iv. count = -limit

FILE TYPES

FILES

All I/O on the QL is to or from a logical file. Various file types exist.

data

SuperBASIC programs, text files. Created using PRINT, SAVE, accessed using INPUT, INKEY$, LOAD etc.

exec

An executable transient program. Saved using SEXEC, loaded using EXEC, EXEC_W etc.

code

Raw memory data, screen images, etc. Saved using SBYTES, loaded using LBYTES.

FUNCTIONS AND PROCEDURES

SuperBASIC functions and procedures are defined with the DEFine FuNction and DEFine PROCedure statements. A function is activated (or called) by typing its name at the appropriate point in a SuperBASIC expression. The function must be included in an expression because it is returning a value and the value must be used. A procedure is activated (or called) by typing its name as the first item

in a SuperBASIC statement.

Data can be passed into a function or procedure by appending a list of actual parameters after the function or procedure name. This list is compared to a similar list appended after te name of the function or procedure when it was defined. This second list is called the formal parameters of the function or

procedure. The formal parameters must be SuperBASIC variables. The actual parameters must be an array, an array slice or a SuperBASIC expression of which a single variable or constant is the simplest form.

Since the actual parameters are actual expressions, they must have an actual type associated with them. The formal parameters are merely used to indicate how the actual parameters must be processed and so have no type associated with them. The items in each list of parameters are paired off in order when the function or procedure is called and the formal parameters become equivalent to the actual parameters. There are three distinct ways of using parameters.

If the actual parameter is a single variable and if data is assigned to the formal parameter in the function or procedure then the data is also assigned to the corresponding actual parameter.

If the actual parameter is an expression then assigning data to the corresponding formal parameter will have no effect outside the procedure. Note that a variable can be turned into an expression by enclosing it within brackets.

if the actual parameter is a variable but has not previously been set then assigning data to the corresponding formal parameter will set the variable specified as the actual parameter.

Variables can be defined to be local to a function or procedure with the LOCal statement. Local variables have no effect on similarly named variables outside the function or procedure in which they are defned and so allow greater freedom in choosing sensible variable names without the risk of corrupting external variables. A local variable is available to any inside function or procedure called from the procedure function in which it is declared to be local unless the function or procedure called contains a further local declaration of the same variable name.

Functions and procedures in SuperBASIC can be used recursively. That is a function or procedure can call itself either directly or indirectly.

Command	Function
DEFine FuNction	define a function
DEFine PROCedure	define a procedure
RETurn	leave a function or procedure (return data from a function)
LOCal	define local data in a function or procedure

GRAPHICS

It is important to realise that the QL screen has non-square pixels and that changing screen mode will change the shape of the pixels. Thus if the grapics procedures were simply pixel based they would draw different shapes in the two modes. For example, in one mode we would have a circle while the same figure in the other mode would be an ellipse.

The graphics procedures ensure that whatever screen mode is in use, consistent figures are produced. It is not possible to use a simple pixel count to indicate sizes of figures, so instead the graphics procedures use an arbitrary scale and coordinate system to specify sizes and positions of figures.

The graphics procedures use the graphics co-ordinate system, i.e. draw relative to the graphics origin which is in the bottom left hand corner of the specified or default window. Note that this is not the same as the pixel origin used to define the position of windows and blocks etc. The graphics origin allows a standard Cartesian coordinate system to be used. A graphics cursor is updated after each graphics operation: subsequent operations can either be relative to this cursor or can be absolute, i.e. relative to the graphics origin.

The scaling factor is such that the full distance in the vertical direction in the specified or default window has length 100 by default and can be changed with the SCALE command. The scale in the x direction is equal to the scale in the y direction. However, the length of line which can be drawn in the x direction is dependent on the shape of the window. Increasing the scale factor increases the maximum size of the figure which can be drawn before the window size is exceeded. If the graphics output is switched to a different size of window then the subsequent size of the output is adjusted to fit the new window. If the figure exceeds its output window then the figure is clipped.

It is useful to consider the window to be a window onto a larger graphics space in which the figures are drawn. The SCALE command allows the graphics origin to be set so allowing the window to be moved around the graphics space.

The graphics procedures are output to the window attached to the specified or default channel and the output is drawn in the INK colour for that channel.

Command	Function
CIRCLE	draw an ellipse or a circle	}
LINE	draw a line	} absolute
ARC	draw an arc of a circle	}
POINT	plot a point	}

CIRCLE_R	draw an ellipse or a circle	}
LINE_R	draw a line	}
ARC_R	draw an arc of a circle	} relative
POINT_R	plot a point	}

SCALE	set scale and move origin
FILL	fill in a shape
CURSOR	position text

Graphics Fill

Figures drawn with the graphics and turtle graphics procedures can be optionally 'filled' with a specified stipple or colour. If FILL is selected then the figure is filled as it is drawn.

The FILL algorithm stores a list of points to plot rather than actually plotting them. When the figure closes there are two points on the same horizontal line. These two points are connected by a line in the current INK colour and the process repeats. Fill must always be reselected before drawing a new figure to ensure that the buffer used to store the list of points is reset.

The following diagram illustrates FILL:

warning

There is an implementation restriction on FILL. FILL must not be used for re-entrant shapes (i.e. a shape which is concave). Re-entrant shapes must be split into smaller shapes which are not re-entrant and each sub-shape filled independently.

IDENTIFIER

A SuperBASIC identifier is a sequence of letters, numbers and underscores.

define:	letter:=		\| a..Z
			\| A..Z

	number:=		\| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 0 \|

	identifier:=		letter * \|\| letter \| number \| _ \| \| *

example:	i.	a
	ii.	limit_1
	iii.	current_guess
	iv.	counter

An identifier must begin with a letter followed by a sequence of letters, numbers and underscores and can be up to 255 characters long. Upper and lower case characters are equivalent.

Identifiers are used in the SuperBASIC system to identify Variables, Procedures, Functions, Repetition loops, etc.

warning

NO meaning can be attributed to an identifier other than its ability to identify constructs to SuperBASIC. SuperBASIC cannot infer the intended use of an identifier from the identifier's name!

JOYSTICK

The joystick ports marked CTL1 and CTL2, allow two joysticks to be attached to the QL.

The joysticks are arranged to generate specific key depressions when moved in a specific way and any program which uses a joystick must be able to adapt to these keys. The QL keyboard can be read directly using the KEYROW function.

	CTL1	CTL2
mode	key	key
up	cursor up	F4
down	cursor down	F2
left	cursor left	F1
right	cursor right	F3
fire	space	F5

comment

The joystick ports can be used for adding other more general purpose control devices to the QL.

Joysticks for other computers using a 9-way 'D' connector require an adaptor to be used with the QL. Such an adaptor is available from Sinclair Research.

KEYWORD

SuperBASIC keywords are identifiers which are defined in the SuperBASIC Keyword

Reference Guide. Keywords have the same form as a SuperBASIC standard

identifier. The case of the keyword is not significant. Keywords are echoed as a

mixture of upper and lower case letters and are always reproduced in full. The

upper case portion indicates the minimum required to be typed in for SuperBASIC

to recognise the keyword.

The set of SuperBASIC keywords may be extended by adding PROCEDURES to the QL.

It is a good idea to define these with their names in upper case and this will

indicate their special function in the SuperBASIC system. Conversely, ordinary

procedures should be defined with their names in lower case.

WARNING: Existing keywords cannot be used as ordinary identifiers within a

SuperBASIC program. SuperBASIC keywords are:

List of Keywords
ABS	DEFine PROCedure	LEN	RANDOMISE
ACOS,ASIN	END DEFine	LET	RND
ACOT,ATAN	DEG	LIST	RECOL
ADATE	DELETE	LOAD	REMark
ARC,ARC_R	DIM	LOCal	RENUM
AT	DIMN	LN,LOG10	REPeat
AUTO	DIR	LRUN	END REPeat
BAUD	DIV	MERGE	RESPR
BEEP	DLINE	MOD	RETurn
BEEPING	EDIT	MODE	RETRY
BLOCK	ELLIPSE	MOVE	RUN
BORDER	ELLIPSE_R	MRUN	SAVE
CALL	EOF	NET	SIN
CHR$	EXEC,EXEC_W	NEW	SCALE
CIRCLE	EXIT	NEXT	SCROLL
CIRCLE_R	EXP	ON GO TO	SDATE
CLEAR	FILL	ON GO SUB	SELect
CLOSE	FILL$	OPEN,OPEN_IN	END SELect
CLS	FLASH	OPEN_NEW	SEXEC
CODE	FOR	OVER	SQRT
CONTINUE	END FOR	PAN	STOP
RETRY	FORMAT	PAPER	STRIP
COPY,COPY_N	GO SUB	PAUSE	TAN
COS	GO TO	PEEK,PEEK_W	TO
COT	IF,THEN,ELSE	PEEK_L	TURN
CSIZE	END IF	PENUP	TURN TO
CURSOR	INK	PENDOWN	UNDER
DATA,READ	INKEY$	PI	VER$
RESTORE	INPUT	POINT,POINT_R	WIDTH
DATE$,DATE	INSTR	POKE,POKE_W	WINDOW
DAY$	INT	POKE_L
DEFine FuNction	KEYROW	PRINT
END DEFine	LBYTES	RAD

MATHS FUNCTIONS

SuperBASIC has the standard trigonometrical and mathematical functions.

Function	Name
COS	cosine
SIN	sin
TAN	tangent

ATAN	arctangent
ACOT	arcotangent

ACOS	arcosine
ASIN	arcsine

COT	cotangent
EXP	exponential
LN	natural logarithm
LOG10	common logarithm

INT	integer
ABS	absolute value

RAD	convert to radians
DEG	convert to degrees

PI	return the value of pi ±

RND	generate a random number
RANDOMISE	reseed the random number generator

MEMORY MAP

The QL contains a Motorola 68008 microprocessor, which can address 1 Megabyte of memory, i.e. from 00000 to FFFFF Hex. The use of addresses within this range are defined by Sinclair Research to be as follows:

The screen RAM is organised as a series of sixteen bit words starting at address Hex 20000 and progressing in the order of the raster scan, i.e. from left to right with each display line and then from the top to the bottom of the picture. The bits within each word are organised so that a pixel to the left is always more significant than a pixel to the right (i.e. the pixel pattern on the screen looks the same as the binary pattern). However, the organisation of the colour information in the two screen modes is different:

Setting the Flash bit toggles the flash state and freezes the background colour for the flash to the value given by R, G and B for that pixel. Flashing is always reset at the beginning of each display line.

In high resolution mode, red and green specified together is interpreted by the hardware as white.

warning

Use of reserved areas in the memory map may cause incompatibility with future Sinclair products. Spurious output to addresses defined to be peripheral I/O addresses can cause unpredictable behaviour. It is recommended that these areas are NOT written to and not used for any other purpose. Poking areas in use as Microdrive buffers can corrupt Microdrive data and can result in a loss of

information. Pokng areas in use such as system tables can cause the system to crash and can result in the loss of data and programs.

All I/O should be performed using either the relevant SuperBASIC commands or the QDOS Operating System traps.

MICRODRIVES

Microdrives provide the main permanent storage on the QL. Each Microdrive cartridge has a capacity of at least 100Kbytes. Available free memory space is allocated by QDOS as Microdrive buffers when necessary to improve performance.

Each blank cartridge must be formatted before use and can hold up to 255 sectors of 512 bytes per sector. QDOS keeps a directory of files stored on the cartridge. Each microdrive file is identified using a standard SuperBASIC file or device name.

A cartridge can be write protected be removing the small lug on the right hand side.

On receiving new blank microdrive cartridges, format them a few times to condition the tape.

general care

Physically each Microdrive cartridge contains a 200 inch loop of high quality video tape which is moved at 28 inches per second. The tape completes one circuit every 7.5 seconds.

NEVER touch the tape with your fingers or insert anything into the cartridge

NEVER turn the computer on or off with cartridges in place

ALWAYS store cartridges in their sleeves when not in use

ALWAYS insert or remove cartridges from the Microdrive slowly and carefully

ALWAYS ensure the cartridge is firmly installed before starting the microdrive

NEVER move the QL with cartridges installed - even if not in operation

NEVER touch the cartridge while the Microdrive is in operation

DO NOT repeatedly insert and remove the cartridge without running the Microdrive

tape loops

If a tape loop appears at either of the two places shown in figure 1 then gently ease it back into the cartridge. Use a non-fibrous instrument for this, e.g. the side of a pen or pencil. NEVER touch the tape with your fingers for this or any reason.

Command	Function
FORMAT	prepare a new cartridge for use
DELETE	delete a file from a cartridge
DIR	list the files on a cartridge
SAVE
SBYTES	saves data from a cartridge
SEXEC
LOAD
LBYTES
EXEC	loads data from a cartridge
MERGE
OPEN_IN
OPEN_NEW
OPEN	opens and closes files
CLOSE
PRINT
INPUT	SuperBASIC file I/O
INKEY$

warning

If you attempt to write to a cartridge which is write protected then the QL will repeatedly attempt to write the data but will eventually give up and give a "bad medium" error.

MONITOR

A monitor may be connected to the QL via the RGB socket on the back of the computer. Connection is via an 8-way DIN plug plus cable for colour monitors, or a 3-way DIN plug plus cable for monochrome. The RGB socket connections are as in the following table, and the column indicating wire colour refers to the colour coding used on the 8-way cable and connector available from Sinclair Research Limited. Pin designation is as shown in the diagram below.

Pin	function	signal		sleeve colour on QL RGB colour lead
1	PAL	composite PAL	(4)	orange
2	GND	ground		green
3	VIDEO	composite monochrome video	(3)	brown
4	CSYNC	composite sync	(2)	yellow
5	VSYNC	vertical sync	(1)	blue
6	GREEN	green	(1)	red
7	RED	red	(1)	white
8	BLUE	blue	(1)	purple

A monochrome monitor can be connected using a screened lead with a 3-way or an 8-way DIN plug at the QL end. Only pins 2 (ground) and 3 (composite video) need to be connected via the cable to the monitor. The connection at the monitor end will vary according to the monitor but is usually a phono plug. The monitor must have a 75 ohm 1V pk-pk composite video non-inverting input (which is the industry standard). Both 3-way DIN plugs and phono plugs are available from audio shops.

Diagram of Monitor Connector as viewed from rear of QL, showing pin numbers and

functions.

Diagram of Monitor Connector as viewed from rear of QL, showing pin numbers and functions

An RGB (colour) monitor can be connected using a lead with an 8 way DIN plug at the QL end. The connection at the monitor end will vary according to the monitor (there is no industry standard) and will often be supplied with it. A suitable cable with an 8-way DIN plug at one end and bare wires at the other end is available from Sinclair Research Limited.

A composite PAL monitor, or the composite video input on some VCRs may work with the QL. Only pins 2 (ground) and 1 (composite PAL) need to be connected via a cable to the monitor or VCR.

NETWORK

The QL can be connected with up to 63 other QLs. If there are more than 2 computers on the network then each computer (or station) must be assigned a unique station number. On the QL this can be done using the NET command.

Information is transmitted over the network in blocks. For normal communication between two stations the receiving station must acknowledge correct reception of the block. If a block is corrupted then the receiving station will request retransmission.

Using a network station number of zero has a special meaning. Sending to neto_0 is called broadcasting: any message sent in this way can be read by any station which is listening to neti_0. Note that the normal verification that a message has been received is disabled for broadcasts, so that broadcasting messages of length more than one block (255 bytes) is unreliable.

A network station which listens to its own station number (e.g. NET3:LOAD neti_3) can receive data from any station sending to it.

Command	Function
NET	assign a network station number
OPEN	open a network channel
CLOSE	close a network channel
PRINT
INPUT	network I/O
INKEY$
LOAD
SAVE
LBYTES
SBYTES
EXEC	load and save via network
SEXEC
LRUN
MRUN
MERGE

comment

If you are planning to connect several QLs on the network, or use a long piece of cable then you should wire it up with low capacitance twin core cable such as 3 amp light flex or bell wire. Take care to connect the centres of each jack to each other, and the outsides to each other. You will find that although the software can handle 63 stations, the hardware will not drive more than about 100m of cable, depending on what type it is.

If you are only connecting a few machines with the lads supplied, you need not worry.

OPERATORS

Operator	Type	Function
=	floating string	logical type 2 comparison
==	numeric string	almost equal ** (type 3 comparison)
+	numeric	addition
-	numeric	subtraction
/	numeric	division
*	numeric	multiplication
<	numeric string	less than (type 2 comparison)
>	numeric string	greater than (type 2 comparison)
<=	numeric string	less than or equal to (type 2 comparison)
>=	numeric string	greater than or equal (type 2 comparison)
<>	numeric string	not equal to (type 3 comparison)
&	string	concatenation
&&	bitwise	AND
\|\|	bitwise	OR
^^	bitwise	XOR
~	bitwise	NOT
OR	logical	OR
AND	logical	AND
XOR	logical	XOR
NOT	logical	NOT
MOD	integer	modulus
DIV	integer	divide
INSTR	string	type 1 string comparison
^	floating	raise to the power
-	floating	unary minus
+	floating	unary plus

**almost equal - equal to 1 part in 10^7

If the specified logical operation is true then a value not equal to zero will be returned. If the operation is false then a value of zero will be returned.

precedence

The precedence of SuperBASIC operators is defined in the table above. If the order of evaluation in an expression cannot be deduced from this table then the relevant operations are performed from left to right. The inbuilt precedence of SuperBASIC operators can be overriden by enclosing the relevant sections of the expression in parentheses.

highest	unary plus and minus
	string concatenation
	INSTR
	exponentiation
	multiply, divide, modulus and integer divide
	add and subtract
	logical comparison
	NOT (bitwise or logical)
	AND (bitwise or logical)
lowest	OR and XOR (bitwise or logical)

PERIPHERAL EXPANSION

The expansion connector allows extra peripherals to be plugged into the QL. The

connections available at the connector are:

The connector on the QL is a 64 way (male) DIN-41612 indirect edge connector.

An 'L' appended to a signal name indicates that the signal is active low.

Signal	Function
A0-A19	68008 address lines
RDWL	Read / Write
ASL	Address Strobe
DSL	Data Strobe
BGL	Bus Grant
DSMCL	Data Strobe - Master Chip
CLKCPU	CPU Clock
E	6800 peripherals clock
RED	Red
BLUE	Blue
GREEN	Green
CSYNCL	Composite Sync
VSYNCH	Vertical Sync
ROMOEH	ROM Output Enable
FC0	Processor status
FC1	Processor status
FC2	Processor status
RESETCPUL	Reset CPU

QL Peripheral Output Signals

Signal	Function
DTACKL	Data acknowledge
BRL	Bus request
VPAL	Valid Peripheral Address
IPL0L	Interrupt Priority Level 5
IPL1L	Interrupt Priority Level 2
BERRL	Bus Error
EXTINTL	External Interrupt
DBGL	Data bus grab

QL Peripheral Input Signals

Signal	Function
D0..D7	Data Lines

QL Peripheral Bi-directional Signals

Signal	Functional
SP0..SP3	Select peripheral 0 to 3
VIN	9V DC (nominal) - 500mA max.
VM12	-12V
VP12	+12V
GND	ground

Miscellaneous

It is not intended that the following description of the QL peripheral expansion mechanism be sufficient to implement an actual expansion device, but rather be read to gain a basic understanding of the expansion mechanism.

Single or multiple peripherals may be added to the QL up to a maximum of 16 devices. A single peripheral can be plugged directly into the QL Expansion Slot while multiple peripherals must be plugged into the QL Expansion Module, which in turn is plugged into the QL Expansion Slot via a buffer card.

In this context the term 'device' also includes expansion memory. Although the areas of the QL memory map allocated to expansion memory are different from those allocate to expansion devices, the basic mechanism is the same. Only one expansion memory peripheral can be plugged into the QL at any one time. The address space allocated for peripheral expansion in the QL Physical memory map allows 16 Kbytes per peripheral. This area must contain the memory mapped I/O required for the driver and the code for the driver itself.

QDOS includes facilities for queue management and simple serial I/O which may be of use when writing device drivers.

The position of each peripheral device in the overall memory map of the QL is determined by the select peripheral lines: SP0, SP1, SP2 and SP3. These select lines generate a signal corresponding to the slot position in the QL expansion module, thus for a device to be selected the address input from address lines: A14, A15, A16 and A17 must be the same as the signals from SP0, SP1, SP2 and SP3

respectively.

PIXEL COORDINATE SYSTEM

The pixel coordinate system is used to define the positions and sizes of windows, blocks and cursor positions on the QL screen. The coordinate system has its origin in the top left hand corner of the default window (or screen) and always assumes that positions are specified as though the screen were in 512 mode (high resolution mode). The system will use the nearest pixel available for the particular mode set making the coordinate system independent of the screen mode in use.

Some commands are always relative to the default window origin, e.g. WINDOW, while some are always relative to the current window origin, e.g. BLOCK

PROGRAM

A SuperBASIC program consists of a sequence of SuperBASIC statements, where each statement is preceded by a line number. Line numbers are in the range of 1 to 32767.

Command	Function
RUN	start a loaded program
LRUN	load a program from a device and start it
[CTRL] [SPACE]	force a program to stop

syntax:	line_number:= [digit]* [range 1,32767]*
	[line_number statement [:statement]]

example:	i.	100 PRINT "This is a valid line number"
		RUN

	ii.	100 REMark a small program
		110 FOR foreground = 0 TO 7
		120 FOR contrast = 0 TO 7
		130 FOR stipple = 0 TO 3
		140 PAPER foreground, contrast, stipple
		150 CURSOR 0,70
		160 FOR n = 0 TO 2
		170 SCROLL 2,1
		180 SCROLL -2,2
		190 END FOR n
		200 END FOR stipple
		210 END FOR contrast
		220 END FOR foreground
		RUN

QDOS

Qdos is the QL Operating System and supervises:

Task Scheduling and resource allocation

Screen I/O (including windowing)

Microdrive I/O

Network and serial channel communication

Keyboard input

Memory management

memory map

A full description of Qdos is beyond the scope of this guide but a brief description is included.

The system RAM has an organisation imposed by the QDOS operating system and is defined as follows:

The terms SV_RAMT, SV_RESPR, SV_TRNSP, SV_BASIC, SV_FREE, SV_HEAP are used to represent addresses inside the QL. These terms are not recognised by SuperBASIC or the QDOS operating system. Furthermore, the addresses represented are liable to change as the system is running.

sv_ramt	RAM Top
	This will vary according to the memory expansion boards attached to the system.

sv_respr	Resident Procedures
	Resident procedures are loaded into the top of RAM. Space can be allocated in the resident procedure area using the RESPR function, but this space cannot be released except by resetting the QL. Resident Procedures written in machine code can be added to the SuperBASIC name list and so become extensions to the SuperBASIC system.

sv_trnsp	Transient Programs
	Transient programs are loaded immediately below the resident procedures. Each program must be self contained, i.e. it must contain space for its own data and its own stack. It must be position independent or must be loaded by a specially written linking loader. A transient program is executed from BASIC by using the EXEC command or from QDOS by activating it as a job.

	The transient program area may be used for storing data only but this data will still be treated by QDOS as a job and therefore must not be activated.

sv_basic	SuperBASIC Area
	This area contains all loaded SuperBASIC programs and related data. This area expands and contracts using up the free space as required.

sv_free	Free Space
	Free space is used by the Qdos file subsystem to create Microdrive Slave Blocks, i.e. copies of Microdrive blocks which can be held in RAM.

sv_heap	System Heap
	This is used by the system to store data channel definitions and also provides working storage for the I/O subsystem. Transient programs may allocate working space for themselves on the heap via Qdos system calls.

	System Tables/System Variables
	This area is directly above the screen memory. The System Tables and supervisor stack are resident above the system variables.

system calls

System calls are processed by Qdos in 'supervisor mode'. When in supervisor mode, Qdos will not allow any other job to take over the processor. System calls processed in this way are said to be 'atomic', i.e. the system call will process to completion before relinquishing the processor. Some system calls are only partially atomic, i.e. once they have completed their primary function they will relinquish the processor if necessary. Unless specifically requested all the system calls are partially atomic.

The standard mechanism for making a system call is by making a trap to one of the Qdos system vectors with appropriate parameters in the processor registers. The action taken by Qdos following a system call is dependent on the particular call and the overall state of the system at the time the call was made.

input/output

Qdos supports a multitasking environemtn and therefore a file can be accessed by more than one process at a time. The Qdos filing sub-system can handle files which have been opened as EXCLUSIVE files or as SHARED files. A shared file cannot be written to. QL devices are processed by the SERIAL I/O SYSTEM. As its name suggests any data output by this system can be redirected to any other

device also supported by the redirectable I/O system.

The device names required by Qdos are the same as the device names required by SuperBASIC and are discussed in the concept section DEVICES. The collection of standard devices supplied with the QL can be expanded.

devices

The standard devices included in the system are discussed in this guide in the section DEVICES. Further devices may be added to the system, given a name (e.g. SER1, NET) and then accessed in the same way as any other QL device.

multitasking

Jobs will be allowed a share of the CPU in line with their priority and competition with other jobs in the system. Jobs running under the control of Qdos can be in one of three states:

active:	Capable of running and sharing system resources. A job in this state may not be runnign continuously but will obtain a share of the CPU in line with its priority.

suspended:	The job is capable of running but is waiting for another job or I/O. A job may be suspended indefinitely or for a specific period of time.

inactive:	The job is incapable of running, its priority is 0 and so it can never obtain a share of the CPU

Qdos will reschedule the system automatically at a rate related to the 50 Hz frame rate. The system will also be rescheduled after certain system calls.

example:	This program generates an on-screen readout of the real-time clock running as an independent job.

	First RUN this program with a formatted cartridge in microdrive 2. This generates a machine code title called 'clock'. Wait for the microdrive to stop. Next, set the clock using the SDATE command.

	Then type:

		EXEC mdv2_clock

	and a continuous time display will appear at the top right of the command window.
		100 c=RESPR(100) 110 FOR i = 0 TO 68 STEP 2 120 READ x:POKE_W i+c,x 130 END FOR i 140 SEXEC mdv2_clock,c,100,256 1000 DATA 29439,29697,28683,20033,17402 1010 DATA 48,13944,200,20115,12040 1020 DATA 28691,20033,17402,74,-27698 1030 DATA 13944,236,20115,8279,-11314 1040 DATA 13944,208,20115,16961,16962 1050 DATA 30463,28688,20035,24794 1060 DATA 0,7,240,10,272,200

N.B. Line 1060 governs the position and colour of the clock window - the data terms are, in order:

border colour/width, paper/ink colour, window width, height, x-origin, y-origin

These are pairs of bytes, entered by POKE_W as words.

The x-origin and the y-origin (the last data item) should be 272 and 202 in monitor mode, or 240 and 216 in TV mode.

Generate the paper and ink word, for example, as 256*paper+ink. Thus white paper, red ink is 256*7 + 2 = 1794

REPETITION

Repetition in SuperBASIC is controlled by two basic program constructs. Each construct must be identified to SuperBASIC:

REPeat identifier	FOR identifier = range
Statements	statements
END REPeat identifier	END FOR identifier

These two constructs are used in conjunction with two other SuperBASIC statements:

NEXT identifier

EXIT identifier

Processing a NEXT statement will either pass control to the statement following the appropriate FOR or REPeat statement, or if a FOR range has been exhausted to the statement following the NEXT.

Prcoessing an EXIT will pass control to the statement after the END FOR or END REPeat selected by the EXIT statement. EXIT can be used to exit through many levels of nested repeat structures. EXIT should always be used in REPeat loops to terminate the loop on some condition.

A combination of NEXT,EXIT and END statements allows FOR and REPeat loops to have a loop epilogue added. A loop epilogue is a series of SuperBASIC statements which are executed on some special condition arising within the loop:

The loop epilogue is only processed if the FOR loop terminates normally. If the loop terminates via an EXIT statement then processing will continue at the END FOR and the epilogue will not be processed.

It is possible to have a similar construction in a REPeat loop:

This time entry into the loop epilogue is controlled by the IF statement. The epilogue will or will not be processed depending on the condition in the IF statement. A SELect statement can also be used to control entry into the epilogue.

ROM CARTRIDGE SLOT

Allows software to be used in the QL system from a Sinclair QL ROM Cartridge. The ROM Cartrdge can contain software to directly change the behaviour of the SuperBASIC system. The cartridge can contain:

i. Software to be used instead of or with the SuperBASIC system. For example:

assemblers

compilers

debuggers

application software

etc

ii. Software to expand the SuperBASIC system. For example:

special procedures

etc

It is not possible to use ZX ROM Cartridges on the QL.

pin out

Side b is the upper side of the connector; side a is the lower.

Signal	Function
A0..A15	Address lines
D0..D7	Data lines
ROMOEH	ROM Output Enable
VDD	5V
GND	Ground

warning:

Never plug or unplug a ROM cartridge while the QL power is on.

SCREEN

512 mode

The screen is 512 pixels across and 256 pixels deep. Only the solid colours

black

red

green

white

can be displayed in this mode.

256 mode

Low resolution mode also has a hardware flash. The screen is 256 pixels across and 256 pixels deep. The full set of solid colours is available in this mode:

black

blue

red

magenta

green

cyan

yellow

white

warning

A domestic television is not capable of displaying the complete QL screen. Portions of the screen at the top and the sides will not be reproduced. The default initial window will take account of this and will reduce the effective picture size. The full size can be restored with the WINDOW command.

Command	Function
MODE	set screen mode

SLICING

Under certain circumstances it is possible to refer to more than one element in an array i.e. slice the array The array slice can be thought of as defining a subarray or a series of subarrays to SuperBASIC. Each slice can define a continuous sequence of elements belonging to a particular dimension of the

original array. The term array in this context can include a numeric array, a string array or a simple string.

It is not necessary to specify an index for the full number of dimensions of an array. If a dimension is omitted then slices are added which will select the full range of elements for that particular dimension, i.e. the slice (0 TO ). SuperBASIC can only add slices to the end of a list of array indices.

syntax:	index: =	\| numeric_exp		{single element}
		\| numeric_exp TO numeric_exp		{range of elements}
		\| numeric_exp TO		{range to end}
		\| TO numeric_expression		{range from beginning}

	array_reference:=		\| variable
			\| variable ( \| index \|,index\| * \| )*

An array slice can be used to specify a source or a destination subarray for an assignment statement.

example:	i.	PRINT data array
	ii.	PRINT letters$(1 TO 15)
	iii.	PRINT two_d_array (3) (2 TO 4)

String slicing is performed in the same way as slicing numeric or string arrays.

Thus

a$(n)	will select the nth character.
a$(n TO m)	will select all characters from the nth to the mth, inclusively
a$(n TO)	will select from a character n to the end, inclusively
a$(1 TO m)	will select from the beginning to the nth character inclusively
a$	will select the entire contents of a a$

Some forms of BASIC have functions called LEFT$, MID$, RIGHTS. These are not necessary in SuperBASIC. Their equivalents are specified below:

SuperBASIC	Other BASIC
a$(n)	MID$(a$,n,1)
a$(n TO m)	MID$ (a$,n,m+1-n)
a$(1 TO n)	LEFT$ (a$,n)
a$(n TO)	RIGHTS (a$,LEN(a$)+1-n)

warning

Assigning data to a sliced string array or string variable may not have the desired effect. Assignments made in this way will not update the length of the string. The length of a string array or string variable is only updated when an assignment is made to the whole string.

START UP

Immediately after switch on (or reset) the QL will perform a RAM test which will give a spurious pattern on the display. If the RAM test is passed then the screen will be cleared and the copyright screen displayed.

After start up, the QL displays the copyright message and asks whether it is being used on a television or a monitor. The QL will set different initial screen modes and window sizes depending on the answer.

Press F1 if you are using a monitor and F2 if you are using a television set.

The QL has the ability to 'boot' itself up from programs contained in either the ROM cartridge slot or in Microdrive 1. If the ROM cartridge slot contains a self starting program then start up will continue under the control of the program in the ROM cartridge. If nothing suitable is found then the QL will check Microdrive 1 for a cartridge. If a cartridge is found and if it contains a file called BOOT it is loaded and run.

default screen

The QL has three default channels which are linked to three default windows.

Channel 0 is used for listing commands and error messages, channel 1 for program and graphics output and channel 2 for program listings. The default channel can be modified using the optional channel specifier in the relevant command.

It is important NOT to switch on the QL with a Microdrive cartridge in position. If booting from a Microdrive cartridge is required then the cartridge must be inserted between switching on and pressing either F1 or F2.

SOUND

Sound on the QL is generated by the QL's second processor (an 8049) and is controlled by specifying:

up to two pitches

the rate at which the sound must move between the pitches, the ramp

how the sound is to behave after it has reached one of the specified pitches, the wrap

if any randomness should be built into the sound, i.e. deviations from the ramp

if any fuzziness should be built into the sound. i.e. deviations on every cycle of the sound

Fuzziness tends to result in buzzy sounds while randomness, depending on the other parameters, will result in 'melodic' sounds or noise.

The complexity of the sound can be built up stage by stage gradually building more complex sounds. This is, in fact, the best way to master sound on the QL.

Specify a duration and a single pitch. The specified pitch will be beeped for the specified time.

LEVEL 1

This is the simplest sound command, other than the command to stop the sound, on the QL.

LEVEL 2

A second pitch and a gradient can be added to the command. The sound will then 'bounce' between the two pitches at the rate specified by the gradient.

The sounds produced at this level can vary between: semi musical beeps, growls, zaps and moans. It is best to experiment.

LEVEL3

A parameter can be added which controls how the sound behaves when it becomes equal to one of the specified pitches. The sound can be made to 'bounce' or 'wrap'.

The number of wraps can be specified, including wrap forever. It is even more important to experiment.

LEVEL4

Randomness can be added to the sound. This is a deviation from the specified step or gradient.

Depending on the amount of randomness added in relation to the pitches and the gradient, it will generate a very wide and unexpected range of sounds.

LEVEL 5

More variation can be added by specifying 'fuzziness'. Fuzziness adds a random factor to the pitch continuously Fuzziness tends to make the sound buzz.

Combining all of the above effects can make a very wide range of sounds, many of them unexpected. QL sound is best explored through experiment. By specifying a time interval of zero the sound can be made to repeat forever and so a sequence of BEEP commands can be used until the sound generated is the sound which is required. A word of warning: slight changes in the value of a single parameter can have alarming results on the sound generated.

STATEMENT

A SuperBASIC statement is an instruction to the QL to perform a specific operation, for example:

LET a = 2

will assign the value 2 to the variable identified by a.

More than one statement can be written on a single line by separating the individual statements from each other by a colon ( : ), for example:

LET a = a + 2 : PRINT a

will add 2 to the value identified by the variable a and will store the result back in a. The answer will then be printed out

If a line is not preceded by a line number then the line is a direct command and SuperBASIC processes the statement immediately. If the statement is preceded by a line number then the statement becomes part of a SuperBASIC program and is added into the SuperBASIC program area for later execution.

Certain SuperBASIC statements can have an effect on the other statements over the rest of the logical line in which they appear i.e. IF, FOR, REPeat, REM, etc. It is meaningless to use certain SuperBASIC statements as direct commands.

STRING ARRAYS, STRING VARIABLES

String arrays and numeric arrays are essentially the same, however there are slight differences in treatment by SuperBASIC. The last dimension of a string array defines the maximum length of the strings within the array. String variables can be any length up to 32766. Both string arrays and string

variables can be sliced.

String lengths on either side of a string assignment need not be equal. If the sizes are not the same then either the right hand string is truncated to fit or the length of the left hand string is reduced to match. If an assignment is made to a sliced string then if necessary the 'hole' defined by the slice will be padded with spaces.

It is not necessary to specify the final dimension of a string array. Not specifying the dimension selects the whole string while specifying a single element will pick out a single character and specifying a slice will define a sub string.

COMMENT: Unlike many BASICs SuperBASIC does not treat string arrays as fixed length strings. If the data stored in a string array is less than the maximum size of the string array then the length of the string is reduced.

WARNING: Assigning data to a sliced string array Or string variable may not have the desired effect. Assignments made in this way will not update the length of the string and so it is possible that the system will not recognise the assignment. The length of a string array or a string variable is only

updated when an assignment is made to the whole string.

Command	Function
FILL$	generate a string
LEN	find the length of a string

STRING COMPARISON

order:

. (decimal point/full stop)

digits or numbers in numerical order

AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz

other non printing characters

The relationship of one string to another may be:

equal:	All characters or numbers are the same or equivalent

lesser:	The first part of the string, which is different from the corresponding character in the second string, is before it in the defined order.

greater:	Thefirst part of the first string which is different from the corresponding character in the second string, is after it in the defined order.

Note that a '.' may be treated as a decimal point in the case of string comparison which sorts numbers (such as SuperBASIC comparisons). Note also that comparison of strings containing non-printable characters may give unexpected results.

types of comparison

type 0 case dependent - character by character comparison

type 1 case independent - character by character

type 2 case dependent - numbers are sorted in numerical order

type 3 case independent - numbers are sorted in numerical order

type 0 not normally used by the SuperBASIC system.

usage

type 1 File and variable comparison

type 2 SuperBASIC <, <=, =, >= ,>, INSTR and <>

type 3 SuperBASIC == (equivalence)

SYNTAX DEFINITIONS

SuperBASlC syntax is defined using a non-rigorous 'meta language' type notation. Four types of construction are used :

	\| \| Select one of
	[ ] Enclosed item(s) are optional
	* * Enclosed items are repeated

	.. Range

	{ } Comment

e.g.	\| A \| B \|	A or B
	[ A ]	A is optional
	* A *	A is repeated
	A..Z	A, B, C, etc
	{this is a comment}

Consider a SuperBASIC identifier.

A sequence of numbers, digits, underscores, starting with a letter and finishing with an optional % or $

letter:=	\| A..Z
	\| a..z
	{a letter is one of:	ABCDEFGHIJKLMNOPQRSTUVWXYZ}
	or	abcdefghijklmnopqrstuvwxyz

digit: =	\| 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \|

Underscore:=	_
	{an underscore is _}

TURTLE GRAPHICS

SuperBASIC has a set of turtle graphics commands:

Command	Function
PENUP	stop drawing
PENDOWN	start drawing
MOVE	move the turtle
TURN	turn the turtle
TURNTO	turn to a specific heading

The set of commands is the minimum and normally would be used within another

procedure to expand on the commands. For example:

100 DEFine PROCedure forward(distance)

110 MOVE distance

120 END DEFine

130 DEFine PROCedure backwards(distance)

140 MOVE -distance

150 END DEFine

160 DEFine PROCedure left(angle)

170 TURN angle

180 END DEFine

190 DEFine PROCedure right(angle)

200 TURN -angle

210 END DEFine

These will define some of the more famous turtle graphic commands.

Initially the turtle's pen is up and the turtle is pointing at 0 degrees which is to the right hand side of the window.

The FILL command will also work with figures drawn with turtle graphics. Also ordinary graphics and turtle graphics can be mixed, although the direction of the turtle is not modified by the ordinary graphics commands.

WINDOWS

Windows are areas of the screen which behave, in most respects, as though each individual window was a screen in its own right, i.e. the window will scroll when it has become filled by text, it can be cleared with the CLS command, etc.

Windows can be specified and linked to a channel when the channel is opened. The current window shape can be changed with the WINDOW command and a border added to a window with the BORDER command. Output can be directed to a window by printing to the relevant channel. Input can be directed to have come from a particular window by inputting from the relevant channel If more than one

channel is ready for input then input can be switched between the ready channels by pressing

[CTRL] C

The cursor will flash in the selected window

Windows can be used for graphics and non-graphic output at the same time. The non graphic output is relative to the current cursor position which can be positioned anywhere within the specified window with the CURSOR command and at any line-column boundary with the AT command. The graphics output is

relative to a graphics cursor which can be positioned and manipulated with the graphics procedures.

PARTS

Certain commands (CLS, PAN etc.) will accept an optional parameter to define part of the current window for their operation. This parameter is as defined below:

part	description
0	whole screen
1	above and excluding cursor line
2	bottom of screen excluding cursor line
3	whole of cursor line
4	line right of and including cursor

Command	Function
WINDOW	re-define a window
BORDER	take a border from a window
PAPER	define the paper colour for a window
INK	define the ink colour for a window
STRIP	define a strip colour for a window
PAN	pan a window's contents
SCROLL	scroll a window's contents
AT	position the print position
CLS	clear a window
CSIZE	set character size
FLASH	character flash
RECOL	recolour a window

expression: =	\| [monop] expression operator expression
	\| (expression)
	\| atom

	atom: =	\| variable
		\| constant
		\| function \| (expression \|, expression )
		\| array_element

		variable: =	\| identifier
			\| identifier %
			\| identifier $

		function: =	\| identifier
			\| identifier %
			\| identifier $

		constant: =	\| digit * [digit] *
			\| [digit] , [digit]
			\| [digit] \|,\| [digit] E [digit]