QL Manual-Keywords
Author: Stephen Berry
Date: 0101-01-01T00:00:00+00:00
Keywords: QL Manual; QL user guide; QL Keywords
Publisher: Sinclair

QL

Keywords

© 1984 SINCLAIR RESEARCH LIMITED

By Stephen Berry (Sinclair Research Limited)

QL KEYWORDS

The Keyword Reference Guide lists all SuperBASIC keywords in alphabetical order: A brief explanation of the keywords function is given followed by loose definition of the syntax and examples of usage. An explanation of the syntax definition is given in the Concept Reference Guide under the entry syntax.

Each keyword entry indicates to which, if any, group of operations it relates, i.e. DRAW is a graphics operation and further information can be obtained from the graphics section of the Concept Reference Guide.

Sometimes it is necessary to deal with more than one keyword at a time, i.e. IF, ELSE, THEN, END, IF, these are all listed under IF.

An index is provided which attempts to cover all possible ways you might describe a SuperBASIC keyword. For example the clear screen command, CLS, is also listed under clear screen and screen clear.

Keyword Index

ABS

ACOS

ASIN

ACOT

ATAN

ADATE

ARC

ARC_R

AT

AUTO

BAUD

BEEP

BEEPING

BLOCK

BORDER

CALL

CHR$

CIRCLE

CIRCLE_R

CLEAR

CLOSE

CLS

CODE

CONTINUE

COPY

COPY_N

COS

COT

CSIZE

CURSOR

DATA

DATE

DATE$

DAY$

DEFine FuNction

DEFine PROCedure

DEG

DELETE

DIM

DIMN

DIR

DIV

DLINE

EDIT

ELLIPSE

ELLIPSE_R

ELSE

END DEFine (Function)

END DEFine (Procedure)

END FOR

END IF

END REPeat

END SELect

EOF

EXEC

EXEC_W

EXIT

EXP

FILL

FILL$

FLASH

FOR

FORMAT

GOSUB

GOTO

IF

INK

INKEY$

INPUT

INSTR

INT

KEYROW

LBYTES

LEN

LET

LINE

LINE_R

LIST

LN

LOAD

LOCAL

LOG10

LRUN

MERGE

MOD

MOVE

MRUN

NET

NEW

NEXT

ON...GOSUB

ON...GOTO

OPEN

OPEN_IN

OPEN_NEW

OVER

PAN

PAPER

PAUSE

PEEK

PEEK_W

PEEK_L

PENDOWN

PENUP

PI

POINT

POINT_R

POKE

POKE_W

POKE_L

PRINT

RAD

RANDOMISE

READ

RECOL

REMark

RENUM

REPEAT

RESPR

RESTORE

RETRY

RETurn

RND

RUN

SAVE

SBYTES

SCALE

SCROLL

SDATE

SELect

SEXEC

SIN

SQRT

STOP

STRIP

TAN

THEN

TURN

TURNTO

UNDER

WIDTH

WINDOW

ABS
maths functions

ABS returns the absolute value of the parameter. It will return the value of the parameter if the parameter is positive and will return zero minus the value of the parameter if the parameter is negative.

syntax:             ABS(numeric_expression)

example:

i. PRINT ABS(0.5)

ii. PRINT ABS(a-b)

ACOS, ASIN, ACOT, ATAN
maths functions

ACOS and ASIN will compute the arc cosine and the arc sine respectively. ACOT will calculate the arc cotangent and ATAN will calculate the arc tangent. There is no effective limit to the size of the parameter.

syntax:             angle:= numeric_expression [in radians]

ACOS (angle)

ACOT (angle)

ASIN (angle)

ATAN (angle)

example:

i.  PRINT ATAN(angle)

ii. PRINT ASIN(1)

iii. PRINT ACOT(3.6574)

iv. PRINT ATAN(a-b)

ADATE
clock

ADATE allows the clock to be adjusted.

syntax:             seconds:= numeric_expression

ADATE seconds

example:

i.        ADATE 3600 {will advance the clock 1 hour}

ii.        ADATE -60  {will move the clock back 1 minute}

ARC, ARC_R
graphics

ARC will draw an arc of a circle between two specified points in the window attached to the default or specified channel. The end points of the arc are specified using the graphics co-ordinate system.

Multiple arcs can be drawn with a single ARC command.

The end points of the arc can be specified in absolute coordinates (relative to the graphics origin or in relative coordinates (relative to the graphics cursor). If the first point is omitted then the arc is drawn from the graphics cursor to the specified point through the specified angle.

ARC will always draw with absolute coordinates, while ARC_R will always draw relative to the graphics cursor.

syntax:             x:= numeric_expression
y:= numeric_expression
angle:= numeric_expression (in radians)

point:= x,y

parameter_2:=   | TO point, angle                       (1)

| ,point TO point,angle               (2)

parameter_1:=   | point TO point,angle                (1)

| TO point,angle                                    (2)

ARC [channel,] parameter_1 *[parameter_2]*

ARC_R [channel,] parameter_1 *[parameter_2]*

Where:

(1)   will draw from the specified point to the next specified point turning through the specified angle

(2)   will draw from the last point plotted to the specified point turning through the specified angle

example:

i.     ARC 15,10 TO 40,40,PI/2

{draw an arc from 15,10 to 40,40 turning through PI/2 radians}

ii.     ARC TO 50,50,PI/2

{draw an arc from the last point plotted to 50,50 turning through PI/2 radians}

iii.     ARC_R 10,10 TO 55,45,0.5

{draw an arc, starting 10,10 from the last point plotted to 55,45 from the start of the arc, turning through 0.5 radians}

AT
windows

AT allows the print position to be modified on an imaginary row/column grid based on the current character size. AT uses a modified form of the pixel coordinate system where (row 0, column 0) is in the top left hand corner of the window. AT affects the print position in the window attached to the specified or default channel.

syntax:             line:= numeric_expression
column:= numeric_expression

AT [channel,] line, column

example:           AT 10,20 : PRINT "This is at line 10 column 20"

AUTO

AUTO allows line numbers to be generated automatically when entering programs directly into the computer. AUTO will generate the next number in sequence and will then enter the SuperBASIC line editor while the line is typed in. If the line already exists then a copy of the line is presented along with the line number. Pressing ENTER at any point in the line will check the syntax of the whole line and will
enter it into the program.

AUTO is terminated by pressing   CTRL   SPACE

Syntax:             first_line:= line_number
gap:= numeric_expression

AUTO [first_line] [,gap]

example:

i.        AUTO                {start at line 100 with intervals of 10}

ii.        AUTO 10,5      {start at line 10 with intervals of 5}

iii.        AUTO ,7          {start at line 100 with intervals of 7}

BAUD
communications

BAUD sets the baud rate for communication via both serial channels. The speed of the channels cannot be set independently.

syntax:             rate:= numeric_expression

BAUD rate

The value of the numeric expression must be one of the supported baud rates on the QL:

75

300

600

1200

2400

4800

9600

19200 (transmit only)

If the selected baud rate is not supported, then an error will be generated.

Example:

i.     BAUD 9600

ii.     BAUD  print_speed

BEEP
sound

BEEP activates the inbuilt sound functions on the QL. BEEP can accept a variable number of parameters to give various levels of control over the sound produced. The minimum specification requires only a duration and pitch to be specified. BEEP used with no parameters will kill any
sound being generated.

syntax:             duration:= numeric_expression    {range -32768..32767}

pitch:= numeric_expression        {range 0..255}

grad_x:= numeric_expression     {range -32768..32767}

grad_y:= numeric_expression     {range -8..7}

wrap:= numeric_expression        {range 0..15}

fuzzy:= numeric_expression        {range 0..15}

random:= numeric_expressian    {range 0..15}

BEEP   [ duration, pitch

[,pitch_2, grad_x, grad_y

[, wrap

[, fuzzy

[, random ]]]]]

duration            specifies the duration of the sound in units of 72 microseconds. A duration of zero will run the sound until terminated by another BEEP command.

pitch                             specifies the pitch of the sound.A pitch of 1 is high and 255 is low.

pitch_2                          specifies an second pitch level between which the sound will 'bounce'

grad_x                          defines the time interval between pitch steps.

grad_y                          defines the size of each step, grad_x and grad_y control the rate at which the pitch bounces between levels.

wrap                             will force the sound to wrap around the specified number of times. If wrap is equal to 15 the sound will wrap around forever:

fuzzy                             defines the amount of fuzziness to be added to the sound.

random                         defines the amount of randomness to be added to the sound.

BEEPING
sound

BEEPING is a function which will return zero (false) if the QL is currently not beeping and a value of one (true) if it is beeping.

syntax:             BEEPING

example:

100 DEFine PROCedure be quiet

110   BEEP

120 END DEFine

130 IF BEEPING THEN be quiet

BLOCK
windows

BLOCK will fill a block of the specified size and shape, at the specified position relative to the origin of the window attached to the specified, or default channel. BLOCK uses the pixel coordinate system.

syntax:             width:= numeric_expression
height:= numeric_expression
x:= numeric_expression
y:= numeric_expression

BLOCK [channel,] width, height, x, y, colour

example:

i.        BLOCK 10,10,5,5,7              {10x10 pixel white block at 5,5}

ii.        100 REMark "bar chart"

110 CSIZE 3,1

120 PRINT "bar chart"

130 LET bottom =100 : size = 20 : left =  10

140 FOR bar =1 to 10

150   LET colour = RND(O TO 255)

160   LET height = RND(2 TO 20)

170   BLOCK size, height, Left+bar*size, bottom-height,0

180   BLOCK size-2, height-2, left+bar*size+l, bottom-height+l,colour

190 END FOR bar

{use LET colour = RND(0 TO 7) for televisions}

BORDER
windows

BORDER will add a border to the window attached to the specified channel, or default channel.

For all subsequent operations except BORDER the window size is reduced to allow space for the BORDER. If another BORDER command is used then the full size of the original window is restored prior to the border being added; thus multiple BORDER commands have the effect of changing
the size and colour of a single border. Multiple borders are not created unless specific action is taken.

If BORDER is used without specifying a colour then a transparent border of the specified width is created.

syntax:             width:= numeric_expression

BORDER [channel,] size [, colour]

example:

i.     BORDER 10,0,7  {black and white stipple border}

ii.     100 REMark Lurid Borders

110 FOR thickness = 50 to 2 STEP -2

120   BORDER thickness, RND(0 TO 255)

130 END FOR thickness

140 BORDER 50

CALL

Qdos

Machine code can be accessed directly from SuperBASIC by using the CALL command. CALL can accept up to 13 long word parameters which will be placed into the 68008 data and address registers (D1 to D7, A0 to A5) in sequence.

No data is returned from CALL.

syntax:             address:= numeric_expression
data:= numeric_expression

CALL address, *[data]*              {13 data parameters maximum}

example:

i.       CALL 262144,0,0,0
ii.     CALL 262500,12,3,4,1212,6

Warning: Address register A6 should not be used in routines called using this command. To return to SuperBASIC use the instructions:

MOVEQ   #0,D0

RTS

CHR$

BASIC

CHR$ is a function which will return the character whose value is specified as a parameter: CHR$ is the inverse of CODE.

syntax:             CHR$(numeric_expression)

example:

i.  PRINT CHRS(27)      {print ASCII escape character}

ii. PRINT CHR$(65)      {print A}

CIRCLE CIRCLE_R
graphics

CIRCLE will draw a circle (or an ellipse at a specified angle) on the screen at a specified position and size. The circle will be drawn in the window attached to the specified or default channel.

CIRCLE uses the graphics coordinate system and can use absolute coordinates (i.e. relative to the graphics origin), and relative coordinates (i.e. relative to the graphics cursor). For relative coordinates use CIRCLE_R.

Multiple circles or ellipses can be plotted with a single call to CIRCLE. Each set of parameters must be separated from each other with a semi colon (;)

The word ELLIPSE can be substituted for CIRCLE if required.

syntax:             x:= numeric_expression
y:= numeric_expession
radius:= numeric_expression
eccentricity:= numeric_expression
angle:= numeric_expression  {range 0 to 2 PI}

parameters:=     | x, y,                                        (1)

| radius, eccentricity, angle         (2)

where     (1) will draw a circle

(2) will draw an ellipse of specified eccentricity and angle

CIRCLE [channel,] parameters*[; parameters]*

x - horizontal offset from the graphics origin or graphics cursor
y - vertical offset from the graphics origin or graphics cursor
radius - radius of the circle
eccentricity - the ratio between the major and minor axes of an ellipse.

angle - the orientation of the major axis of the ellipse relative to the screen vertical. The angle must be specified in radians.

example:

i.        CIRCLE 50,50,20           {a circle at 50,50 radius 20}

ii.        CIRCLE 50,50,20,0.5,0   {an ellipse at 50,50 major axis 20 eccentricity 0.5
and aligned with the vertical axis}

CLEAR

CLEAR will clear out the SuperBASIC variable area for the current program and will release the space for Qdos.

syntax:             CLEAR

example:           CLEAR

Comment: CLEAR can be used to restore to a known state the SuperBASIC system. For example, if a program is broken into (or stops due to an error) while it is in a procedure then SuperBASIC is still in the
procedure even after the program has stopped. CLEAR will reset the SuperBASIC. {See CONTINUE, RETRY.}

CLOSE
devices

CLOSE will close the specified channel. Any window associated with the channel will be deactivated.

syntax:             channel:= #numeric_expression

CLOSE channel

example:           i.  CLOSE #4
ii. CLOSE #input, channel

CLS
windows

Will clear the window attached to the specified or default channel to current PAPER colour, excluding the border if one has been specified. CLS will accept an optional parameter which specifies if only a part
of the window must be cleared.

syntax:             part:= numeric_expression

CLS [channel,] [part]

where:               part = 0 - whole screen (default if no parameter)

part = 1 - top excluding the cursor line
part = 2 - bottom excluding the cursor line
part = 3 - whole of the cursor line
part = 4 - right end of cursor line including the cursor position

example:

i.        CLS                  {the whole window}

ii.        CLS 3               {clear the cursor line}

iii.        CLS #2,2          {clear the bottom of the window on channel 2}

CODE

CODE is a function which returns the internal code used to represent the specified character. If a string is specified then CODE will return the internal representation of the first character of the string.

CODE is the inverse of CHR$.

syntax:             CODE (string_expression)

example:

i.   PRINT CODE("A")             {prints 65}

ii.   PRINT CODE ("SuperBASIC")   {prints 83}

CONTINUE  RETRY
error handling

CONTINUE allows a program which has been halted to be continued. RETRY allows a program statement which has reported an error to be re-executed.

syntax:             CONTINUE

RETRY

example:           CONTINUE

RETRY

warning:

A program can only continue if:

1.     No new lines have been added to the program

2.     No new variables have been added to the program

3.     No lines have been changed

The value of variables may be set or changed.

COPY  COPY_N
devices

COPY will copy a file from an input device to an output device until an end of file marker is detected. COPY_N will not copy the header (if it exists) associated with a file and will allow Microdrive files to
be correctly copied to another type of device.

Headers are associated with directory-type devices and should be removed using COPY_N when copying to non-directory devices, e.g. mdv1 is a directory device; ser1 is a non-directory device.

syntax:             COPY device TO device

COPY_N device TO device

It must be possible to input from the source device and it must be possible to output to the destination device.

example:

i. COPY mdvl_data_file TO con_          {copy to default window}

ii. COPY neti_3 TO mdvl_data               {copy data from network station
to mdv_data.}

iii. COPY_N mdvl_test_data TO ser1_   {copy mdvl_test_data to serial port 1 removing  header information}

COS
maths functions

COS will compute the cosine of the specified argument.

syntax:             angle:= numeric_expression       {range -10000..10000 in radians}

COS (angle)

example:

i.  PRINT COS(theta)

ii.  PRINT C0S(3.141592654/2)

COT
maths functions

COT will compute the cotangent of the specified argument.

syntax:             angle:= numeric_expression       {range -30000..30000 in radians}

COT (angle)

example:

i.   PRINT COT(3)

ii.  PRINT COT(3.141592654/2)

CSIZE
window

Sets a new character size for the window attached to the specified or default channel. The standard size is 0,0 in 512 mode and 2,0 in 256 mode.

Width defines the horizontal size of the character space. Height defines the vertical size of the character space. The character size is adjusted to fill the space available.

Figure A Character Square

width

size

Height

size·

0

6 pixels

0

10 pixels

1

8 pixels

1

20 pixels

2

12 pixels

3

16 pixels

syntax:             width:= numeric_expression   {range 0..3}

height:= numeric_expression   {range 0..11}

CSIZE [channel,]- width, height

example:           i. CSIZE 3,0
ii. CSIZE 3,1

CURSOR
windows

CURSOR allows the screen cursor to be positioned anywhere in the window attached to the specified or default channel.

CURSOR uses the pixel coordinate system relative to the window origin and defines the position for the top left hand corner of the cursor. The size of the cursor is dependent on the character size in use.

If CURSOR is used with four parameters then the first pair is interpreted as graphics coordinates (using the graphics coordinate system) and the second pair as the position of the cursor (in the
pixel coordinate system) relative to the first point.

This allows diagrams to be annotated relatively easily.

syntax:             x:= numeric_expression
y:= numeric_expression

CURSOR [channel,] x, y [,x, y]

example:           i. CURSOR 0,0

ii. CURSOR 20,30
iii. CURSOR 50,50,10,10

DATA  READ  RESTORE

BASIC

READ, DATA and RESTORE allow embedded data, contained in a SuperBASIC program, to be assigned to variables at run time.

DATA is used to mark and define the data, READ accesses the data and assigns it to variables and RESTORE allows specific data to be selected.

DATA                           allows data to be defined within a program. The data can be read by a READ statement and the data assigned to variables. A DATA statement is ignored by SuperBASIC when it is encountered during normal processing.

syntax:              DATA *[expression,]*

READ                           reads data contained in DATA statements and assigns it to a list of variables. Initially the data pointer is set to the first DATA statement in the program and is incremented after each READ. Re-running the program will not reset the data pointer and so in general a program should contain an explicit RESTORE.

An error is reported if a READ is attempted for which there is no DATA.

syntax:              READ *[identifier,l*

RESTORE        restores the data pointer, i.e. the position from which subsequent READs will read their data. If RESTORE is followed by a line number then the data pointer is set to that line. If no parameter is specified then the data pointer is reset to the start of the program.

syntax:             RESTORE [line_number]

example:

i.     100 REMark Data statement example

110 DIM weekdays$(7,4)

120 RESTORE

130 FOR count= 1 TO 7 : READ weekdays$(count)

140 PRINT weekday$

150 DATA "MON","TUE","WED","THUR","FRI"

160 DATA "SAT","SUN"

ii.     100 DIM month$(l2,9)

110 RESTORE

120 REMark Data statement example

130 FOR count=l TO 12 : month$(count)

140 PRINT month$

150 DATA "January", "February", "March"

160 DATA "April","May","June"

170 DATA "July","August","September"

180 DATA "October","November","December"

Warning:

An implicit RESTORE is not performed before running a program. This allows a single program to run with different sets of data. Either include a RESTORE in the program or perform an explicit RESTORE or CLEAR before running the program.

DATE$  DATE
clock

DATE$ is a function which will return the date and time contained in the QL’s clock. The format of the string returned by DATE$ is:

"yyyy mmm dd hh:mm:ss"

where:

yyyy

is the year 1984, 1985, etc

mmm

is the month Jan, Feb etc

dd

is the day 01 to 28, 29, 30, 31

hh

is the hour 00 to 23

mm

are the minutes 00 to 59

ss

are the seconds 00 to 59

DATE will return the date as a floating point number which can be used to store dates and times in a compact form.

If DATE$ is used with a numeric parameter then the parameter will be interpreted as a date in floating point form and will be converted to a date string.

syntax:

DATE$

{get the time from the clock)

DATE$ (numeric_expression)

{get time from supplied parameter}

example:

i. PRINT DATE$

{output the date and time}

ii. PRINT DATE$(234567)

{convert 234567 to a date}

DAY$
clock

DAY$ is a function which will return the current day of the week. If a parameter is specified then DAY$ will interpret the parameter as a date and will return the corresponding day of the week.

syntax:

DAY$

{get day from clock}

DAY$ (numeric_expression)

{get day from supplied parameter}

example:

i. PRINT DAY$

{output the day}

ii. PRINT DAY$(234567)

{output the day represented by 234567 (seconds)}

DEFine   FuNction   END DEFine
functions and procedures

DEFine FuNction defines a SuperBASIC function. The sequence of statements between the DEFine function and the END DEFine constitute the function. The function definition may also include a list of
formal parameters which will supply data for the function. Both the formal and actual parameters must be enclosed in brackets. If the function requires no parameters then there is no need to specify an
empty set of brackets.

Formal parameters take their type and characteristics from the corresponding actual parameters. The type of data returned by the function is indicated by the type appended to the function identifier.

The type of the data returned in the RETURN statement must match.

An answer is returned from a function by appending an expression to a RETurn statement. The type of the returned data is the same as type of this expression.

A function is activated by including its name in a SuperBASIC expression.

Function calls in SuperBASIC can be recursive; that is, a function may call itself directly or indirectly via a sequence of other calls.

Syntax:

formal_parameters= (expression *[, expression]*)

actual_parameters:= (expression *[, expression]*)

type:=

| $

| %

|

DEF FuNction identifier type {formal_parameters}

[LOCal identifier x[, identifier]*]

statements

RETurn expression

END DEFine

RETurn can be at any position within the procedure body. LOCal statements must preceed the first executable statement in the function.

example:

10 DEFine FuNction mean(a, b, c)

20   LOCaL answer

30   LET answer = (a + b + c)/3

40   RETurn answer

50 END DEFine

60 PRINT mean(1,2,3)

Comment:

To improve legibility of programs the name of the function can be appended to the END DEFine statement. However, the name will not be checked by SuperBASIC.

DEFine   PROCedure  END DEFine
functions and procedures

DEFine PROCedure defines a SuperBASIC procedure. The sequence of statements between the DEFine PROCedure statement and the END DEFine statement constitutes the procedure. The procedure definition may also include a list of formal parameters which will supply data for the
procedure. The formal parameters must be enclosed in brackets for the procedure definition, but the brackets are not necessary when the procedure is called. If the procedure requires no parameters then
there is no need to include an empty set of brackets in the procedure definition.

Formal parameters take their type and characteristics from the corresponding actual parameters.

Variables may be defined to be LOCal to a procedure. Local variables have no effect on similarly named variables outside the procedure. If required, local arrays should be dimensioned within the LOCal
statement.

The procedure is called by entering its name as the first item in a SuperBASIC statement together with a list of actual parameters. Procedure calls in SuperBASIC are recursive that is, a procedure may call itself directly or indirectly via a sequence of other calls.

It is possible to regard a procedure definition as a command definition in SuperBASIC; many of the system commands are themselves defined as procedures.

syntax:

formal_parameter:= (expression *[, expression]*)

actual_parameters:= expression *[, expression]*

DEFine PROCedure identifier {forma_parameters}

[LOCal identifier *[, identifier]*]

statements

[RETurn]

END DEFine

RETURN can appear at any position within the procedure body. If present the LOCal statement must be before the first executable statement in the procedure. The END DEFine statement will act as an automatic return.

example:

i.

100 DEFine PROCedure start_screen

110   WINDOW 100,100,10,10

120   PAPER 7 : INK O : CLS

130   BORDER 4,255

140   PRINT "Hello Everybody"

150 END DEFine

160 start_screen

ii.

100  DEFine  PROCedure  slow_scroll(scroll_limit)

110   LOCal count

120   FOR count = 1 TO scroll

130      SCROLL 2

140   END FOR count

150 END DEFine

160 slow_scroll 20

Comment:

To improve legibility of programs the name of the procedure can be appended to the END DEFine statement. However, the name will not be checked by SuperBASIC.

DEG
math functions

DEG is a function which will convert an angle expressed in radians to an angle expressed in degrees.

syntax:             DEG(numeric_expression)

example:           PRINT DEG(PI/2)          {will print 90}

DELETE
microdrives

DELETE will remove a file from the directory of the cartridge in the specified Microdrive.

syntax:             DELETE device

The device specification must be a Microdrive device

Example:          i.  DELETE mdv1_old_data
ii. DELETE mdv1_letter_file

DIM

Arrays

Defines an array to SuperBASIC. String, integer and floating point arrays can be defined. String arrays handle fixed length strings and the final index is taken to be the string length.

Array indices run from 0 up to the maximum index specified in the DIM statement; thus DIM will generate an array with one more element in each dimension than is actually specified.

When an array is specified it is initialised to zero for a numeric array and zero length strings for a string array.

syntax:

index:= numeric_expression

array:= indentifier(index *[, index]*)

DIM array *[, array] *

example:

i. DIM string_array$(10,10,50)

ii. DIM matrix(100,100)

DIMN
arrays

DIMN is a function which will return the maximum size of a specified dimension of a specified array. If a dimension is not specified then the first dimension is assumed. If the specified dimension does not
exist or the identifier is not an array then zero is returned.

Syntax:

array:=  identifier

index:= numeric_expression {1 for dimension 1, etc.}

DIMN(array [, dimension])

example:

consider the array defined by:  DIM a(2,3,4)

i. PRINT DIMN(A,1)

{will print 2}

ii. PRINT DIMN(A,2)

{will print 3}

iii. PRINT DIMN(A,3)

{will print 4}

iv. PRINT DIMN(A)

{will print 2}

v. PRINT DIMN(A,4)

{will print 0}

DIR

Microdrives

DIR will obtain and display in the window attached to the specified or default channel  Microdrives the directory of the cartridge in the specified Microdrive.

Syntax:

DIR device

The device specification must be a valid Microdrive device

The directory format output by DIR is as follows:

free_sectors:=

the number of free sectors

available_sectors:=

the maximum number of sectors on this cartridge

file_name:=

a SuperBASIC file name

screen format:

Volume name

free_sectors | available_sectors sectors

file_name

......

file__name

example:

i. DIR mdv1_

ii. DIR "mdv2_ "

iii. DIR "mdv" & microdrive_number$ & "_"

screen format:

BASIC

183 / 221 sectors

demo_1

demo_1_old

demo_2

DIV
operator

DIV is an operator which will perform an integer divide.

syntax:  numeric_expression DIV numeric_expression

example:

i. PRINT 5 DIV 2

{will output 2}

ii. PRINT -5 DIV 2

{will output -3}

DLINE

BASIC

DLINE will delete a single line or a range of lines from a SuperBASIC program.

syntax:

range:=

| line_number TO line_number

1

| line_number TO

2

| TO line_number

3

| line_number

4

DLINE range*[,range]*

where

1  will delete a range of lines

2  will delete from the specified line to the end

3  will delete from the start to the specified line

4  will delete the specified line

example:

i.

DLINE 10 TO 70, 80, 200 TO 400

{will delete lines 10 to 70 inclusive, line 80 and lines 200 to 400 inclusive}

ii.

DLINE

{will delete nothing}

EDIT

The EDIT command enters the SuperBASIC line editor.

The EDIT command is closely related to the AUTO command, the only difference being in their defaults. EDIT defaults to a line increment of zero and thus will edit a single line unless a second parameter is
specified to define a line increment.

If the specified line already exists then the line is displayed and editing can be started. If the line does not exist then the line number is displayed and the line can be entered.

The cursor can be manipulated within the edit line using the standard QL keystrokes.

→   cursor right

→   cursor left

↑    cursor up  -  same as ENTER but automatically gives previous existing line to edit next

↓    cursor down -  same as ENTER but automatically gives next existing line to edit next

CTRL   →    delete character right

CTRL   ←    delete character left

When the line is correct pressing ENTER will enter the line into the program.

If an increment was specified then the next line in the sequence will be edited otherwise edit will terminate.

syntax:

increment:= numeric_expression

EDIT line_number [,increment]

example:

i.

EDIT 10

{edit line 10 only}

ii.

EDIT 20,10

{edit lines 20, 30 etc.}

EOF

Devices

EOF is a function which will determine if an end of file condition has been reached on a specified channel. If EOF is used without a channel specification then EOF will determine if the end of a program's embedded data statements has been reached.

syntax:

EOF [(channel)]

example:

i.

IF EOF(#6) THEN STOP

ii.

IF EOF THEN PRINT "Out of data"

EXEC   EXEC_W

Qdos

EXEC and EXEC_W will load a sequence of programs and execute them in parallel.

EXEC will return to the command processor after all processes have started execution, EXEC_W will wait until all the processes have terminated before returning.

syntax:

program: =device

{used to specify a Microdrive file containing the program}

EXEC program

example:

i.

EXEC mdv1_communcations

ii.

EXEC_W mdv1_printer_process

EXIT

Repetition

EXIT will continue processing after the END of the named FOR or REPeat structure.

syntax:

EXIT identifier

example:

i.

100 REM start Looping

110 LET count = 0

120 REPeat Loop

130   LET count = count +1

140   PRINT count

150   IF count = 20 THEN EXIT Loop

160 END REPeat loop

{the loop will be exited when
count becomes equal to 20}

ii.

100 FOR n =1 TO 1000

110   REM program statements

120   REM program statements

130   IF RND >.5 THEN EXIT n

140 END FOR n

{the loop will be exited when a random

Number greater than 0.5 is generated}

EXP
maths functions

EXP will return the value of e raised to the power of the specified parameter.

syntax:

EXP (numeric_expression)

{range -500..500}

example:

i.

PRINT EXP(3)

ii.

PRINT EXP(3.141592654)

FILL
graphics

FILL will turn graphics fill on or off. FILL will fill any non-re-entrant shape drawn with the graphics or turtle graphics procedures as the shape is being drawn. Re-entrant shapes must be split into smaller non-re-entrant shapes.

When you have finished filling, FILL 0 should be called.

Syntax:

switch:= numeric_expression

{range 0..1}

FILL [channel,] switch

example:

i.

FILL 1:LINE 10,10 TO 50,50 TO 30,90 TO 10,10:FILL 0

{will draw a filled triangle}

ii.

FILL 1:CIRCLE 50,50,20:FILL 0

{will draw a filled circle}

FILL$
string arrays

FILL$ is a function which will return a string of a specified length filled with a repetition of one or two characters.

syntax:

FILL$ (string_expression, numeric_expression)

The string expression supplied to FILL$ must be either one or two characters long.

example:

i.

PRINT FILL$("a",5)

{will print aaaaa}

ii.

PRINT FILL$("oO",7)

{will print oOoOoOo}

iii.

LET a$ = a$ & FILL$(" ",10)

FLASH
windows

FLASH turns the flash state on and off. FLASH is only effective in low resolution mode. FLASH will be effective in the window attached to the specified or default channel.

syntax:

switch:= numeric_expression

{range 0..1}

FLASH [channel,] switch

where:

switch = 0 will turn the flash off

switch = 1 will turn the flash on

example:

100 PRINT "A ";

110 FLASH 1

120 PRINT "flashing ";

130 FLASH 0

140 PRINT "word"

Warning:

Writing over part of a flashing character can produce spurious results and should be avoided.

FOR      END FOR
repetition

The FOR statement allows a group of SuperBASIC statements to be repeated a controlled number of times. The FOR statement can be used in both a long and a short form.

NEXT and END FOR can be used together within the same FOR loop to provide a loop epilogue, i.e. a group of SuperBASIC statements which will not be executed if a loop is exited via an EXIT statement but which will be executed if the FOR loop terminated normally.

define:

for_item:=

| numeric_expression

| numeric_exp TO numeric_exp

| numeric_exp TO numeric_exp STEP numeric_exp

for_list. =

for_item *[, for_item] *

SHORT:

The FOR statement is followed on the same logical line by a sequence of SuperBASIC statements. The sequence of statements is then repeatedly executed under the control of the FOR statement. When the

FOR statement is exhausted, processing continues on the next line. The FOR statement does not require its terminating NEXT or END FOR. Single line FOR loops must not be nested.

syntax:

FOR variable = for_list : statement *[: statement]*

example:

i.

FOR i = 1,2,3,4 TO 7 STEP 2 : PRINT i

ii.

FOR element=first TO last:LET buffer(element )=0

LONG:

The FOR statement is the last statement on the line. Subsequent lines contain a series of SuperBASIC statements terminated by an END FOR statement. The statements enclosed between the FOR statement and the END FOR are processed under the control of the FOR statement.

syntax:

FOR variable = for_list

Statements

END FOR variable

example:

100 INPUT "data please"  x

110 LET factorial = 1

120 FOR value = x TO 1 STEP -1

130   LET factorial = factorial * value

140   PRINT x !!!! factorial

150   IF factorial>lE20 THEN

160     PRINT "Very Large number"

170     EXIT value

180   END IF

190 END FOR value

Warning:

A floating point variable must be used to control a FOR loop.

FORMAT
microdrives

FORMAT will format and make ready for use the cartridge contained in the specified Microdrive.

syntax:

FORMAT [channel,] device

Device specifies the Microdrive to be used for formatting and the identifier part of the specification is used as the medium or volume name for that cartridge. FORMAT will write the number of good sectors
and the total number of sectors available on the cartridge on the default or on the specified channel.

It is helpful to format a new cartridge several times before use. This conditions the surface of the tape and gives greater capacity.

example:

i.

FORMAT mdv1_data_cartridge

ii.

FORMAT mdv2_wp_letters

FORMAT can be used to reinitialise a used cartridge. However all data contained on that cartridge will be lost.

GOSUB

For compatibility with other BASICs, SuperBASIC supports the GOSUB statement. GOSUB transfers processing to the specified line number; a RETurn statement will transfer processing back to the statement following GOSUB.

The line number specification can be an expression.

syntax:

GOSUB line_number

example:

i.

GOSUB 100

ii.

GOSUB 4*select_variable

Comment:

The control structures available in SuperBASIC make the GOSUB statement redundant.

GOTO

For compatibility with other BASICs, SuperBASIC supports the GOTO statement. GOTO will unconditionally transfer processing to the statement number specified. The statement number specification can be an expression.

syntax:

GOTO line_number

example:

i.

GOTO program

ii.

GOTO 9999

comment:

The control structures available in SuperBASIC make the GOTO statement redundant.

IF   THEN   ELSE   END IF

The IF statement allows conditions to be tested and the outcome of that test to control subsequent program flow.

The IF statement can be used in both a long and a short form:

SHORT:

The THEN keyword is followed on the same logical line by a sequence of SuperBASIC keyword. This sequence of SuperBASIC statements may contain an ELSE keyword. If the expression in the IF statement is true (evaluates to be non-zero), then the statements between the THEN and the ELSE keywords are processed. If the condition is false (evaluates to be zero) then the statements between the ELSE and the end of the line are processed.

If the sequence of SuperBASIC statements does not contain an ELSE keyword and if the expression in the IF statement is true, then the statements between the THEN keyword and the end of the line are
processed. If the expression is false then processing continues at the next line.

syntax:

statements:= statement *[: statement]*

IF expression THEN statements [:ELSE statements]

example:

i.

IF a=32 THEN PRINT "Limit" : ELSE PRINT "OK"

ii.

IF test >maximum THEN LET maximum = test

iii.

IF "1"+1=2 THEN PRINT "coercion OK"

long 1:

The THEN keyword is the last entry on the logical line. A sequence of SuperBASIC statements is written following the IF statements. The sequence is terminated by the END IF statement. The sequence of SuperBASIC statements is executed if the expression contained in the IF statement evaluates to be non zero. The ELSE keyword and second sequence of SuperBASIC statements are optional.

long 2:

The THEN keyword is the last entry on the logical line. A sequence of SuperBASIC statements follows on subsequent lines, terminated by the ELSE keyword. IF the expression contained in the IF statement evaluates to be non zero then this first sequence of SuperBASIC statements is processed. After the ELSE keyword a second sequence of SuperBASIC statements is entered, terminated by the END IF keyword. If the expression evaluated by the IF statement is zero then this second sequence of SuperBASIC statements is processed.

syntax:

IF expression THEN

Statements

[ELSE

statements]

END IF

example:

100 LET limit = 10

110 INPUT "Type in a number" ! number

120 IF number > limit THEN

130   PRINT "Range error"

140 ELSE

150   PRINT "Inside Limit"

160 END IF

In all three forms of the IF statement the THEN is optional. In the short form it must comment be replaced by a colon to distinguish the end of the IF and the start of the next statement. In the long form it
can be removed completely.

IF statements may be nested as deeply as the user requires (subject to available memory).  However, confusion may arise as to which ELSE, END IF etc matches which IF. SuperBASIC will match nested ELSE statements etc to the closest IF statement, for example:

100 IF a = b THEN

110   IF c = d THEN

120     PRINT "error"

130   ELSE

140     PRINT "no error"

150   END IF

160 ELSE

170   PRINT "not checked"

180 END IF

The ELSE at line 130 is matched to the second IF. The ELSE at line 160 is matched with the first IF (at line 100).

INK
windows

This sets the current ink colour, i.e. the colour in which the output is written. INK will windows be effective for the window attached to the specified or default channel.

syntax:

INK [channel,] colour

example:

i.

INK 5

ii.

INK 6,2

iii.

INK #2,255

INKEY$

INKEY$ is a function which returns a single character input from either the specified or default channel.

An optional timeout can be specified which can wait for a specified time before returning, can return immediately or can wait forever. If no parameter is specified then INKEY$ will return immediately.

syntax:

INKEY$

[|(channel)

|(channel, time)

|(time)]

where:

time = 1..32767

{wait for specified number of frames}

time = -1

{wait forever}

time = 0

{return immediately}

examples:

i.

PRINT INKEY$

{input from the default channel}

ii.

PRINT INKEY$(#4)

{input from channel 4}

iii.

PRINT INKEY$(50)

{wait for 50 frames then return anyway}

iv.

PRINT INKEY$(0)

{return immediatly (poll the keyboard)}

v.

PRINT INKEY$(#3,100)

{wait for 100 frames for an input from channel 3 then return anyway}

INPUT

INPUT allows data to be entered into a SuperBASIC program directly from the QL keyboard by the user. SuperBASIC halts the program until the specified amount of data has been input; the program will then continue. Each item of data must be terminated by the ENTER key.

INPUT will input data from either the specified or the default channel.

If input is required from a particular console channel the cursor for the window connected to that channel will appear and start to flash.

syntax:

separator:=

|!

|,

|\

|;

| TO

prompt:= [channel,] expression separator

INPUT [prompt] [channel] variable *[,variable]*

example:

i.

INPUT ("Last guess "& guess & "New guess?") ! guess

ii.

INPUT "What is your guess?"; guess

iii.

100 INPUT "array size?" ! Limit

110 DIM array(limit-1)

120 FOR element = 0 to Limit-1

130   INPUT ("data for element" & element) array(element)

140 END FOR element

150 PRINT array

INSTR

Operator

INSTR is an operator which will determine if a given substring is contained within a specified string. If the string is found then the substring's position is returned. If the string is not found then INSTR returns zero.

Zero can be interpreted as false, i.e. the substring was not contained in the given string. A non zero value, the substrings position, can be intepreted as true, i.e. the substring was contained in the specified
string.

syntax:

string_expression INSTR string expression

example:

i.

PRINT "a" INSTR "cat"

{will  print 2}

ii.

PRINT "CAT" INSTR "concatenate"

{will print 4}

iii.

PRINT "x" INSTR "eggs"

{will print 0}

INT
maths functions

INT will return the integer part of the specified floating point expression.

syntax:

INT (numeric_expression)

example:

i.

PRINT INT(X)

ii.

PRINT INT(3.141592654/2)

KEYROW

KEYROW is a function which looks at the instantaneous state of a row of keys (the table below shows how the keys are mapped onto a matrix of 8 rows by 8 columns). KEYROW takes one parameter, which must be an integer in the range 0 to 7: this number selects which row is to be looked at. The value returned by KEYROW is an integer between 0 and 255 which gives a binary representation indicating which keys have been depressed in the selected row.

Since KEYROW is used as an alternative to the normal keyboard input mechanism using INKEY$ or INPUT, any character in the keyboard type-ahead buffer are cleared by KEYROW: thus key depressions which have been made before a call to KEYROW will not be read by a subsequent INKEY$ or INPUT.

Note that multiple key depressions can cause surprising results. In particular, if three keys at the corner of a rectangle in the matrix are depressed simultaneously, it will appear as if the key at the fourth corner has also been depressed. The three special keys CTRL, SHIFT and ALT are an exception to this rule, and do not interact with other keys in this way.

syntax:

row:= numeric_expression     {range 0..7}

KEYROW (row)

example:

100 REMark run this program and press a few keys

110 REPeat loop

120   CURSOR 0,0

130   FOR row = 0 to 7

140     PRINT row  !!! KEYROW(row) ;" "

150   END FOR row

160 END REPeat Loop

KEYBOARD MATRIX

COLUMN

ROW

1

2

4

8

16

32

64

128

7

SHIFT

CTRL

ALT

X

V

/

N

.

6

8

2

6

Q

E

0

T

U

5

9

W

I

TAB

R

-

Y

O

4

L

3

H

1

A

P

D

J

3

I

CAPS

LOCK

K

S

F

=

G

;

2

|

Z

.

C

B

£

M

~

1

ENTER

←

↑

ESC

→

\

SPACE

↓

0

F4

F1

5

F2

F3

F5

4

7

LBYTES
devices
microdrives

LBYTES will load a data file into memory at the specified start address.

syntax:

start_address:= numeric_expression

LBYTES device, startaddress

example:

i.

LBYTES mdvl_screen, 131072

{load a screen image}

iii.

ii.

LBYTES mdvl_program, start_address

{load a program at a specified address}

LEN
string arrays

LEN is a function which will return the length of the specified string expression.

syntax:

LEN (string_expression)

example:

i.

PRINT LEN("LEN will find the length of this string")

ii.

PRINT LEN(output_string$)

LET

LET starts a SuperBASIC assignment statement. The use of the LET keyword is optional. The assignment may be used for both string and numeric assignments. SuperBASIC will automatically convert unsuitable data types to a suitable form wherever possible.

syntax:

[LET] variable = expression

example:

i.

LET a = 1 + 2

ii.

LET a$ = "12345"

iii.

LET a$ = 6789

iv.

b$ = test_data

LINE   LINE_R

Graphics

LINE allows a straight line to be drawn between two points in the window attached to the default or specified channel. The ends of the line are specified using the graphics coordinate system.

Multiple lines can be drawn with a single LINE command.

The normal specification requires specifying the two end points for a line. These end points can be specified either in absolute coordinates (relative to the graphics origin) or in relative coordinates (relative
to the graphics cursor). If the first point is omitted then a line is drawn from the graphics cursor to the specified point. If the second point is omitted then the graphics cursor is moved but no line is drawn.

LINE will always draw with absolute coordinates, i.e. relative to the graphics origin, while LINE_R will always draw relative to the graphics cursor.

syntax:

x:= numeric_expression

y:= numeric_expression

point:= x,y

parameter_2:=

| TO point

(1)

| ,point XO point

(2)

parameter_1:=

| TO point, angle

(1)

| TO point

(2)

| point

(3)

LINE [channel,] parameter_1 *[, parameter_2]*

LINE_R [channel,] parameter_1 *[,parameter_2]*

where

(1) will draw from the specified point to the next specified point

(2) will draw from the the last point plotted to the specified point

(3) will move to the specified point - no line will be drawn

example:

i.  LINE 0,0 TO 0,50 TO 50,0 TO 50,0 TO 0,0

{a square}

ii. LINE TO 0.75, 0.5

{a line}

iii.LINE 25,25

{move the graphics cursor}

LIST

LIST allows a SuperBASIC line or group of lines to be listed on a specific or default channel.

CTRL

SPACE

LIST is terminated by

syntax:

line:=

| line_number TO line_number

(1)

| line_number TO

(2)

| TO line_number

(3)

| line_number

(4)

|

(5)

LIST [channel,] line*[,line]*

Where

(1) will list from the specified line to the specified line

(2) will list from the specified line to the end

(3) will list from the start to the specified line

(4) will list the specified line

(5) will list the whole program

Example:

i.

LIST

{list all lines}

ii.

LIST 10 TO 300

{list lines 10 to 300}

iii.

LIST 12,20,50

{list lines 12,20 and 50 only}

If LIST output is directed to a channel opened as a printer channel then LIST will provide hard copy.

LOAD
devices

Microdrives

LOAD will load a SuperBASIC program from any QL device. LOAD automatically performs a NEW before loading another program, and so any previously loaded program will be cleared by LOAD.

If a line input during a load has incorrect SuperBASIC syntax, the word MISTAKE is inserted between the line number and the body of the line. Upon execution, a line of this sort will generate an error.

Syntax:

LOAD device

example:

i.

LOAD "mdv1_test_program"

ii.

LOAD mdv1_guess

iii.

LOAD neti_3

iv.

LOAD ser1_e

LN   LOG10
maths functions

LN will return the natural logarithm of the specified argument. LOG10 will return the common logarithm. There is no upper limit on the parameter other than the maximum number the computer can store.

syntax:

LOG10 (numenic_expression)

{range greater than zero}

LN (numeric_expression)

{range greater than zero}

example:

i.

PRINT LOG10(20)

ii.

PRINT LN(3.141592654)

LOCal
functions and procedures

LOCal allows identifiers to be defined to be LOCal to a function or procedure. Local identifiers only exist within the function or procedure in which they are defined, or in procedures and functions called from the function or procedure in which they are defined. They are lost when the function or procedure terminates. Local identifiers are independent of similarly named identifiers outside the defining function or procedure. Arrays can be defined to be local by dimensioning them within the LOCal statement.

The LOCal statement must precede the first executable statement in the function or procedure in which it is used.

syntax:

LOCal identifier *[, identifier]*

example:

i.

LOCal a,b,c(10,10)

ii.

LOCal temp_data

comment:

Defining variables to be LOCal allows variable names to be used within functions and procedures without corrupting meaningful variables of the same name outside the function or procedure.

LRUN
devices

Microdrives

LRUN will load and run a SuperBASIC program from a specified device. LRUN will perform NEW before loading another program and so any previously stored SuperBASIC program will be cleared by LRUN.

If a line input during a loading has incorrect SuperBASIC syntax, the word MISTAKE is inserted between the line number and the body of the line. Upon execution, a line of this sort will generate an error.

syntax:

LRUN device

example:

i.

LRUN mdv2_TEST

ii.

LRUN mdv1_game

MERGE
devices

Microdrives

MERGE will load a file from the specified device and interpret it as a SuperBASIC program. If the new file contains a line number which doesn't appear in the program already in the QL then the line will be
added. If the new file contains a replacement line for one that already exists then the line will be replaced. All other old program lines are left undisturbed.

If a line input during a MERGE has incorrect SuperBASIC syntax, the word MISTAKE is inserted between the line number and the body of the line. Upon execution, a line of this sort will generate an error.

syntax:

MERGE device

example:

i.

MERGE mdv1_overlay_program

ii.

MERGE mdv1_new_data

MOD
operators

MOD is an operator which gives the modulus, or remainder; when one integer is divided by another.

syntax:

numeric_expression MOD numeric_expression

example:

i.

PRINT 5 MOD 2

{will print 1}

ii.

PRINT 5 MOD 3

{will print 2}

MODE
screen

MODE sets the resolution of the screen and the number of solid colours which it can display. MODE will clear all windows currently on the screen, but will preserve their position and shape. Changing to low
resolution mode (8 colour) will set the minimum character size to 2,0.

syntax:

MODE numeric_expression

where:

8 or 256 will select low resolution mode

4 or 512 will select high resolution mode

example:

i.

MODE 256

ii.

MODE  4

MOVE
turtle graphics

MOVE will move the graphics turtle in the window attached to the default or specified channel a specified distance in the current direction. The direction can be specified using the TURN and TURNTO commands. The graphics scale factor is used in determining how far the turtle actually moves. Specifying a negative distance will move the turtle backwards.

The turtle is moved in the window attached to the specified or default channel.

syntax:

distance:= numeric_expression

MOVE [channel,] distance

example:

i.

MOVE #2,20

{move the turtle in channel 2 20 units forwards}

ii.

MOVE -50

{move the turtle in the default channel 50 units backwards}

MRUN
devices

Microdrives

MRUN will interpret a file as a SuperBASIC program and merge it with the currently loaded program.

If used as direct command MRUN will run the new program from the start. If used as a program statement MRUN will continue processing on the line following MRUN.

If a line input during a merge has incorrect SuperBASIC syntax, the word MISTAKE is inserted between the line number and the body of the line. Upon execution, a line of this sort will generate an error.

syntax:

MRUN device

example:

i.

MRUN mdv1_chain_program

ii.

MRUN mdv1_new_data

NET
network

NET allows the network station number to be set. If a station number is not explicitly set then the QL assumes station number 1.

syntax:

station:= numeric_expression

{range 1..127}

NET station

example:

i.

NET 63

ii.

NET  1

comment

Confusion may arise if more than one station on the network has the same station number:

NEW

NEW will clear out the old program, variables and channels other than 0,1 and 2.

syntax:

NEW

example:

NEW

NEXT
repetition

NEXT is used to terminate, or create a loop epilogue in REPeat and FOR loops.

syntax:

NEXT identifier

The identifier must match that of the loop which the NEXT is to control

example:

i.

10 REMark this loop must repeat forever

11 REPeat infinite loop

12 PRINT "sti LI looping"

13 NEXT infinite loop

ii.

10 REMark this loop will repeat 20 times

11 LET limit = 20

12 FOR index=1 TO Limit

13   PRINT index

14 NEXT index

iii.

10 REMark this Loop will tell you when a 30 is found

11 REPeat Loop

12   LET number = RND(1 TO 100)

13   IF number = 30 THEN NEXT Loop

14   PRINT number; " is 30"

15 EXIT LOOP

16 END REPeat loop

If NEXT is used inside a REPeat - END REPeat construct it will force processing to continue at the statement following the matching REPeat statement.

The NEXT statement can be used to repeat the FOR loop with the control variable set at its next value. If the FOR loop is exhausted then processing will continue at the statement following the NEXT;
otherwise processing will continue at the statement after the FOR.

ON...GOTO     ON...GOSUB

To provide compatibility with other BASICs, SuperBASIC supports the ON GOTO and ON GOSUB statements. These statements allow a variable to select from a list of possible line numbers a line to process in a GOTO or GOSUB statement. If too few line numbers are specified in the list then an error is generated.

syntax:

ON variable GOTO expression *[, expression]*

ON variable GOSUB expression *[, expression]*

example:

i.

ON x GOTO 10, 20, 30, 40

ii.

ON select_variable GOSUB 1000,2000,3000,4000

comment:

SELect can be used to replace these two BASIC commands.

OPEN   OPEN_IN   OPEN_NEW
devices

Microdrives

OPEN allows the user to link a logical channel to a physical QL device for I/O purposes.

If the channel is to a Microdrive then the Microdrive file can be an existing file or a new file. In which case OPEN_IN will open an already existing Microdrive file for input and OPEN_NEW will create a new Microdrive file for output.

syntax:

channel:= # numeric_expression

OPEN channel, device

example:

i.

OPEN #5, f_name$

ii.

OPEN_IN #9,"mdv1_filename"

{open file mdv1_file_name}

iii.

OPEN_NEW #7,mdv1_datafile

{open file mdvl_datafile}

iv.

OPEN #6,con_10x20a20x20_32

{Open channel 6 to the console device creating a window size 10x20 pixels at position 20,20 with a 32 byte keyboard type ahead buffer.}

v.

OPEN #8,mdv1_read_write_file.

OVER
windows

OVER selects the type of over printing required in the window attached to the specified or default channel. The selected type remains in effect until the next use of OVER.

syntax:

switch:= numeric_expression

{range -1..1}

OVER [channel,] switch

Where

switch = 0 - print ink on strip

switch = 1 - print in ink on transparent strip

switch = -1 - XORs the data on the screen

example:

i.

OVER 1          {set "overprinting")

ii.

10 REMark Shadow Writing

11 PAPER 7 : INK O : OVER 1 : CLS

12 CSIZE 3,1

13 FOR i = 0 TO 10

14   CURSOR i,i

15   IF i = 10 THEN INK 2

16   PRINT "Shadow"

17 END FOR i

PAN
windows

PAN the entire current window the specified number of pixels to the left or the right. PAPER is scrolled in to fill the clear area.

An optional second parameter can be specified which will allow only part of the screen to be panned.

syntax:

distance:= numeric_expression

part:= numeric_expression

PAN [channel,] distance [, part]

where

part = 0 - whole screen (or no parameter)

part = 3 - whole of the cursor line

part = 4 - right end of cursor line including the cursor position

If the expression evaluates to a positive value then the contents of the screen will be shifted to the right.

example:

i.

PAN #2,50

{pan left 50 pixels}

ii.

PAN  -100

{pan right 100 pixels}

iii.

PAN  50,3

{pan the whole of the current cursor line 50 pixels to the right}

warning:

If stipples are being used or the screen is in low resolution mode then, to maintain the stipple pattern, the screen must be panned in multiples of two pixels.

PAPER
windows

PAPER sets a new paper colour (i.e. the colour which will be used by CLS, PAN, SCROLL, etc). The selected paper colour remains in effect until the next use of PAPER. PAPER will also set the STRIP colour

PAPER will change the paper colour in the window attached to the specified or default channel.

syntax:

PAPER [channel,] colour

example:

i.

PAPER #3,7

{White paper on channel 3}

ii.

PAPER 7,2

{White and red stipple}

iii.

PAPER 255

{Black and white stipple}

iv.

10 REMark Show colours and stipples

11 FOR colour = 0 TO 7

12   FOR contrast = 0 TO 7

13     FOR stipple = 0 TO 3

14       PAPER colour, contrast, stipple

15        SCROLL 6

16     END FOR stipple

17   END FOR cent rest

18 END FOR colour

{not suitable for televisions}

PAUSE

PAUSE will cause a program to wait a specified period of time delays are specified in units of 20ms in the UK only, otherwise 16.67ms. If no delay is specified then the program will pause indefinitely. Keyboard input will terminate the PAUSE and restart program execution.

syntax:

delay:= numeric_expression

PAUSE [delay]

example:

i.

PAUSE 50

{wait 1 second}

ii.

PAUSE 500

{wait 10 seconds}

PEEK   PEEK_W   PEEK_L

BASIC

PEEK is a function which returns the contents of the specified memory location. PEEK has three forms which will access a byte (8 bits), a word (16 bits), or a long word (32 bits).

syntax:

address:= numeric_expression

PEEK(address)

{byte access}

PEEK_W(address)

{word access}

PEEK_L(address)

{long word access}

example:

i.

PRINT PEEK(12245)

{byte contents of location 12245}

ii.

PRINT PEEK_W(12)

{word contents of locations 12 and 13}

iii.

PRINT PEEK_L(1000)

{long word contents of location 1000}

Warning:

For word and long word access the specified address must be an even address.

PENUP   PENDOWN
turtle graphics

Operates the 'pen' in turtle graphics. If the pen is up then nothing will be drawn. If the pen is down then lines will be drawn as the turtle moves across the screen.

The line will be drawn in the window attached to the specified or default channel. The line will be drawn in the current ink colour for the channel to which the output is directed.

syntax:

PENUP [channel]

PENDOWN [channel]

example:

i.

PENUP

{will raise the pen in the default channel}

ii.

PENDOWN #2

{will lower the pen in the window attached to channel 2}

PI
maths function

PI is a function which returns the value of x.

syntax:

PI

example:

PRINT PI

POINT   POINT_R
graphics

POINT plots a point at the specified position in the window attached to the specified or default channel. The point is plotted using the graphics coordinates system relative to the graphics origin. If POINT_R is used then all points are specified relative to the graphics cursor and are plotted relative to each other.

Multiple points can be plotted with a single call to POINT.

Syntax:

x:=numeric_expression

y:=numeric_expression

parameters:= x,y

POINT [channel,] parameters* [,parameters]*

example:

i.

POINT 256,128

{plot a point at (256,128)}

ii.

POINT x,x*x

{plot a point at (x,x*x)}

iii.

10 REPeat example

20   INK RND(255)

30   POINT RND(100),RND(100)

40 END REPeat example

POKE   POKE_W   POKE_L

BASIC

POKE allows a memory location to be changed. For word and long word accesses the specified address must be an even address.

POKE has three forms which will access a byte (8 bits), a word (16 bits), a long word (32 bits).

syntax:

address:= numeric_expression

data:= numeric_expression

POKE address, data

{byte access}

POKE_W address, data

{word access}

POKE_L address, data

{long word access}

example:

i.

POKE 12235,0

{set byte at 12235 to 0}

ii.

POKE_L 131072,12345

{set long word at 131072 to 12345}

Warning:

Poking data into areas of memory used by Qdos can cause the system to crash and data to be lost. Poking into such areas is not recommended.

PRINT
devices

Microdrives

Allows output to be sent to the specified or default channel. The normal use of PRINT is to send data to the QL screen.

Syntax:

separator:=

| !

|  ,

| \

| ;

|  TO numeric_expression

item:=

| expression

| channel

| separator

PRINT *[item]*

Multiple print separators are allowed. At least one separator must separate channel specifications and expressions.

Example:

i.

PRINT  "Hello  World"

{will output Hello World on the default output device (channel 1)}

ii.

PRINT #5,"data",1,2,3,4

{will output the supplied data to channel 5 (which must have been previously opened)}

iii.

PRINT TO 20; "This is in column 20"

separators

!

Normal action is to insert a space between items output on the screen. If the item will not fit on the current line a line feed will be generated. If the current print position is at the start of a line then a space will not be output.  ! affects the next item to be printed and therefore must be placed in front of the print item being printed.  Also a ; or a ! must be placed at the end of a print list if the spacing is to be continued over a series of PRINT statements.

,

Normal separator, SuperBASIC will tabulate output every 8 columns.

\

Will force a new line.

;

Will leave the print position immediately after the last item to be printed. Output will be printed in one continuous stream.

TO

Will perform a tabbing operation. TO followed by a numeric_expression will advance the print position to the column specified by the numeric_expression. If the requested column is meaningless or the current print position is beyond the specified position then no action will be taken.

RAD
maths functions

RAD is a function which will convert an angle specified in degrees to an angle specified in radians.

syntax:

RAD (numeric_expression)

example:

PRINT RAD(180)

{will print 3.141593}

RANDOMISE
maths functions

RANDOMISE allows the random number generator to be reseeded. If a parameter is specified the parameter is taken to be the new seed. If no parameter is specified then the generator is reseeded from internal information.

syntax:

RANDOMISE [numeric_expression]

example:

i.

RANDOMISE

{set seed to internal data}

ii.

RANDOMISE  3.2235

{set seed to 3.2235}

RECOL
windows

RECOL will recolour individual pixels in the window attached to the specified or default channel according to some preset pattern. Each parameter is assumed to specify, in order, the colour in which each pixel is recoloured, i.e. the first parameter specifies the colour with which to recolour all black pixels, the second parameter blue pixels, etc.

The colour specification must be a solid colour, i.e. it must be in the range 0 to 7.

syntax:

c0:= new colour for black

c1:= new colour for blue

c2:= new colour for red

c3:= new colour for magenta

c4:= new colour for green

c5:= new colour for cyan

c6:= new colour for yellow

c7:= new colour for white

RECOL [channel,] c0, cl, c2, c3, c4, c5, c6, c7

example:

RECOL 2,3,4,5,6,7,1,0

{recolour blue to magenta, red to green, magenta to cyan etc.}

REMark

REMark allows explanatory text to be inserted into a program. The remainder of the line is ignored by SuperBASIC.

syntax:

REMark text

example:

REMark This is a comment in a program

comment:

REMark is used to add comments to a program to aid clarity.

RENUM

RENUM allows a group or a series of groups of SuperBASIC line numbers to be changed. If no parameters are specified then RENUM will renumber the entire program. The new listing will begin at line 100 and proceed in steps of 10.

If a start line is specified then line numbers prior to the start line will  be unchanged. If an end line is specified then line numbers following the end line will be unchanged.

If a start number and stop are specified then the lines to be renumbered will be numbered from the start number and proceed in steps of the specified size.

If a GOTO or GOSUB statement contains an expression starting with a number then this number is treated as a line number and is renumbered.

syntax:

startline:=

numeric_expression

{start renumber}

end_line:=

numeric_expression

{stop renumber}

start_number:=

numeric_expression

{base line number}

step:=

numeric_expression

{step}

RENUM [start_line [TO end_line];] [startnumber] [,step]

example:

i.

RENUM

{renumber whole program from 100 by 10}

ii.

RENUM 100 TO 200

{renumber from 100 to 200 by 10}

Comment:

No attempt must be made to use RENUM to renumber program lines out of sequence, i.e. to move lines about the program. RENUM should not be used in a program.

REPeat   END REPeat
repetition

REPeat allows general repeat loops to be constructed. REPeat should be used with EXIT for maximum effect. REPeat can be used in both long and short forms:

short:

The REPEAT keyword and loop identifer are followed on the same logical line by a colon and a sequence of SuperBASIC statements. EXIT will resume normal processing at the next logical line.

syntax:

REPeat identifier : statements

example:

REPeat wait : IF INKEY$ = "" THEN EXIT wait

long:

The REPEAT keyword and the loop identifier are the only statements on the logical line. Subsequent lines contain a series of SuperBASIC statements terminated by an END REPeat statement.

The statements between the REPeat and the END REPeat are repeatedly processed by SuperBASIC.

syntax:

REPeat identifier

Statements

END REPeat identifier

example:

10 LET number = RND(1 TO 50)

11 REPeat guess

12   INPUT "What is your guess?", guess

13   IF guess = number THEN

14     PRINT "You have guessed correctly"

15     EXIT guess

16  ELSE

17     PRINT "You have guessed incorrectly"

18  END IF

19 END REPeat guess

Comment:

Normally at least one statement in a REPeat loop will be an EXIT statement.

RESPR

Qdos

RESPR is a function which will reserve some of the resident procedure space. (For example to expand the SuperBASIC procedure list.)

syntax:

space:= numeric_expression

RESPR (space)

example:

PRINT RESPR(1024)

{will print the base address of a 1024 byte block}

RETurn
functions and procedures

RETurn is used to force a function or procedure to terminate and resume processing at the statement after the procedure or function call. When used within a function definition them RETurn statement is
used to return the function's value.

syntax:

RETurn [expression]

example:

i.

100 PRINT ack (3,3)

110  DEFine FuNction ack(m,n)

120   IF m=0 THEN RETurn n+1

130   IF n=0 THEN RETurn ack(m-1,1)

140   RETurn ack (m-1,ack(m,n-1))

150 END DEFine

ii.

10 LET  warning_flag = 1

11 LET error_number = RND(0 TO 10)

12 warning error_number

13 DEFine PROCedure warning(n)

14   IF warning_flag THEN

15     PRINT "WARNING:";

16     SELect ON n

17       ON n =1

18         PRINT "Microdrive  full"

19       ON n = 2

20         PRINT "Data space full"

21       ON n = REMAINDER

22         PRINT "Program error"

23     END SELect

24   ELSE

25     RETurn

26   END IF

27 END DEFine

comment

It is not compulsory to have a RETurn in a procedure. If processing reaches the END DEFine of a procedure then the procedure will return automatically.

RETurn by itself is used to return from a GOSUB.

RND
maths function

RND generates a random number. Up to two parameters may be specified for RND. If no parameters are specified then RND returns a pseudo random floating point number in the exclusive range 0 to 1. If a
single parameter is specified then RND returns an integer in the inclusive range 0 to the specified parameter. If two parameters are specified then RND returns an integer in the inclusive range specified
by the two parameters.

syntax:

RND( [numeric_expression] [TO numeric_expression])

example:

i.

PRINT RND

{floating point number between 0 and 1}

ii.

PRINT RND(10  TO  20)

{integer between 10 and 20}

iii.

PRINT RND(1 TO 6)

{integer between 1 and 6}

iv.

PRINT RND(10)

{integer between 0 and 10}

RUN
program

RUN allows a SuperBASIC program to be started. If a line number is specified in the RUN command then the program will be started at that point, otherwise the program will start at the lowest line number.

syntax:

RUN [numeric_expression]

example:

i.

RUN

{run from start}

ii.

RUN 10

{run from line 10}

iii.

RUN 2*20

{run  from  line  40}

Comment:

Although RUN can be used within a program its normal use is to start program execution by typing it in as a direct command.

SAVE
devices

Microdrives

SAVE will save a SuperBASIC program onto any QL device.

syntax:

line:=

| numeric_expression TO numeric_expression

(1)

| numeric_expression TO

(2)

| TO numeric_expression

(3)

| numeric_expression

(4)

|

(5)

SAVE device *[,line]*

Where

(1) will save from the specified line to the specified line

(2) will save from the specified line to the end

(3) will save from the start to the specified line

(4) will save the specified line

(5) will save the whole program

example:

i.

SAVE mdv1_program,20 TO 70

{save lines 20 to 70 on mdv1_program}

ii.

SAVE mdv2_test_program,10,20,40

{save lines 10,20,40 on mdv1_test_program}

iii.

SAVE net3

{save the entire program on the network}

iv.

SAVE ser1

{save the entire program on serial channel }

SBYTES
devices

Microdrives

SBYTES allows areas of the QL memory to be saved on a QL device

syntax:

start_address:=

numeric_expression

length:=

numeric_expression

SBYTES device, start_address, length

example:

i.

SBYTES mdv1_screendata,131072,32768

{save memory 50000 length 10000 bytes on mdv1_test_program}

ii.

SBYTES mdv1_test_program,50000,10000

{save memory 50000 length 1000 bytes on mdv1_test_program}

iii.

SBYTES neto_3,32768,32678

{save memory 32768 length 32768 bytes on the network}

iv.

SBYTES ser1,0,32768

{save memory 0 length 32768 bytes on serial channel 1}

SCALE
graphics

SCALE allows the scale factor used by the graphics procedures to be altered. A scale of 'x' implies that a vertical line of length 'x' will fill the vertical axis of the window in which the figure is drawn. A scale of 100 is the default. SCALE also allows the origin of the coordinate system to be specified. This effectively allows the window being used for the graphics to be moved around a much larger graphics space.

syntax:

x:=numeric_expression

y:=numeric_expression

origin:= x,y

scale:= numeric_expression

SCALE [channel,] scale, origin

example:

i.

SCALE 0.5,0.1,0.1

{set scale to 0.5 with the origin at 0.1,0.1}

ii.

SCALE 10,0,0

{set scale to 10 with the origin at 0,0}

iii.

SCALE 100,50,50

{set scale to 100 with the origin at 50,50}

SCROLL
windows

SCROLL scrolls the window attached to the specified or default channel up or down by the given number of pixels. Paper is scrolled in at the top or the bottom to fill the clear space.

An optional third parameter can be specified to obtain a part screen scroll.

syntax:

part:=

numeric_expression

distance:=

numeric_expression

where

part = 0 - whole screen (default is no parameter)

part = 1 - top excluding the cursor line

part = 2 - bottom excluding the cursor line

SCROLL [channel,] distance [, part]

If the distance is positive then the contents of the screen will be shifted down.

example:

i.

SCROLL 10

{scroll down 10 pixels}

ii.

SCROLL -70

{scroll up 70 pixels}

iii.

SCROLL -10,2

{scroll the lower part of the window up 10 pixels}

SDATE
clock

The SDATE command allows the QCs clock to be reset.

syntax:

year:= numeric_expression

month:= numeric_expression

day:= numeric_expression

hours:= numeric_express,on

minutes:= numeric_expression

seconds:= numeric_expression

SDATE year, month, day, hours, minutes, seconds

example:

i.

SDATE 1984,4,2,0,0,0

ii.

SDATE 1984,1,12,9,30,0

iii.

SDATE 1984,3,21,0,0,0

SELect   END SELect
conditions

SELect allows various courses of action to be taken depending on the value of a variable.

define:

select_variable:= numeric_variable

select_item:=

| expression

| expression TO expression

select_list:=

| select_item *[, select_item]*

long:

Allows multiple actions to be selected depending on the value of a select_variable. The select variable is the last item on the logical line. A series of SuperBASIC statements follows, which is terminated by the next ON statement or by the END SELect statement. If the select item  is an expression then a check is made within approximately 1 part in 10-7, otherwise for expression TO expression the range is tested exactly and is inclusive. The ON REMAINDER statement allows a, "catch-all" which will respond if no other select conditions are satisfied.

syntax:

SELect ON select_variable

*[[ON select_variable] = select_list

statements] *

[ON selectvariable] = REMAINDER

Statements

END SELect

example:

100 LET error number = RND(1 TO 10)

110 SELect ON error_number

120   ON error_number =1

130     PRINT "Divide by zero"

140     LET error_number = 0

150   ON error_number = 2

160      PRINT "File not found"

170      LET error_number = 0

180   ON error_number = 3 TO 5

190      PRINT "Microdrive file not found"

200      LET error_number = 0

210   ON error_number = REMAINDER

220     PRINT "Unknown error"

230 END SELect

If the select variable is used in the body of the SELect statement then it must match the select variable given in the select header.

short:

The short form of the SELect statement allows simple single line selections to be made. A sequence of SuperBASIC statements follows on the same logical line as the SELect statement. If the condition defined in the select statement is satisfied then the sequence of SuperBASIC statements is processed.

syntax:

SELect ON select_variable = select_list : statement *[:statement] *

example:

i.

SELect ON test data =1 TO 10 : PRINT "Answer within range"

ii.

SELect ON answer = 0.00001 TO 0.00005 : PRINT "Accuracy OK"

iii.

SELect ON a =1 TO 10 : PRINT a ! "in  range"

comment:

The short form of the SELect statement allows ranges to be tested more easily than with an IF statement. Compare example ii. above with the corresponding IF statement.

SEXEC

Qdos

Will save an area of memory in a form which is suitable for loading and executing with the EXEC command.

The data saved should constitute a machine code program.

syntax:

start_address:=

numeric_expression

{start of area}

length:=

numeric_expression

{length of area}

data_space:=

numeric_expression

{length of data area which will be required by the program}

SEXEC device, start_address, length, data_space

example:

SEXEC mdv1_program,262144,3000,500

comment:

The Qdos system documentation should be read before attempting to use this command.

SIN
maths function

SIN will compute the sine of the specified parameter.

syntax:

angle:= numeric_expression

{range -10000..10000 in radians}

SIN(angle)

example:

i.

PRINT SIN(3)

ii.

PRINT SIN(3.141592654/2)

SQRT
maths function

SQRT will compute the square root of the specified argument. The argument must be greater maths functions than or equal to zero.

syntax:

SQRT (numeric_expression)

{range >= 0}

example:

i.

PRINT SQRT(3)

{print square root of 3}

ii.

LET C = SQRT(a^2+b^2)

{let c become equal to the square root of a^2 + b^2}

STOP

BASIC

STOP will terminate execution of a program and will return SuperBASIC to the command interpreter.

syntax:

STOP

example:

i.

STOP

ii.

IF  n = 100 THEN STOP

You may CONTINUE after STOP.

comment:

The last executable line of a program will act as an automatic stop.

STRIP
windows

STRIP will set the current strip colour in the window attached to the specified or default channel. The strip colour is the background colour which is used when OVER 1 is selected. Setting PAPER will automatically set the strip colour to the new PAPER colour.

syntax:

STRIP [channel,] colour

example:

i.

STRIP 7

{set a white strip}

ii.

STRIP 0,4,2

{set a black and green stipple strip}

Comment:

The effect of STRIP is rather like using a highlighting pen.

TAN
maths functions

TAN will compute the tangent of the specified argument. The argument must be in the range -30000 to 30000 and must be specified in radians.

syntax:

TAN (numeric_expression)

{range -30000..30000}

example:

i.

TAN(3)

{print tan 3}

ii.

TAN(3.141592654/2)

{print tan PI/2}

TURN   TURNTO
turtle graphics

TURN allows the heading of the 'turtle' to be turned through a specified angle while TURNTO allows the turtle to be turned to a specific heading.

The turtle is turned in the window attached to the specified or default channel.

The angle is specified in degrees. A positive number of degrees will turn the turtle anti-clockwise and a negative number will turn it clockwise. Initially the turtle is pointing at 0 degrees, that is, to the right hand side of the window.

syntax:

angle:= numeric_expression

{angle in degrees}

TURN [channel,] angle

TURNTO [channel,] angle

example:

i.

TURN 90

{turn through 90 degrees}

ii.

TURNTO 0

{turn to heading 0 degrees}

UNDER
windows

Turns underline either on or off for subsequent output lines. Underlining is in the current INK colour in the window attached to the specified or default channel.

syntax:

switch:= numeric_expression

{range 0..1}

UNDER [channel,] switch

example:

i.

UNDER 1

{underlining on}

ii.

UNDER 0

{underlining off}

WIDTH
windows

WIDTH allows the default width for non-console based devices to be specified, for example printers.

syntax:

line_width:= numeric_expression

WIDTH [channel,] line_width

example:

i.

WIDTH 80

{set the device width to 80}

ii.

WIDTH #6,72

{set the width of the device attached to channel 6 to 72}

WINDOW
windows

Allows the user to change the position and size of the window attached to the specified or default channel. Any borders are removed when the window is redefined. Coordinates are specified using the pixel system relative to the screen origin.

syntax:

width:= numeric_expression

depth:= numeric_expression

x:=numeric_expression

y:=numeric_expression

WINDOW [channel,] width, depth, x, y

example:

WINDOW 30, 40, 10, 10

{window 30x40 pixels at 10,10}

Table of Contents

- ABS
- ACOS
- ADATE
- ARC
- AT
- AUTO
- BAUD
- BEEP
- BEEPING
- BLOCK
- BORDER
- CALL
- CHR$
- CIRCLE
- CLEAR
- CLOSE
- CLS
- CODE
- CONTINUE
- COPY
- COS
- COT
- CSIZE
- CURSOR
- DATA
- DATE
- DAY$
- DEFine FuNction
- DEFine PROCedure
- DEG
- DELETE
- DIM
- DIMN
- DIR
- DIV
- DLINE
- EDIT
- ELSE
- END FOR
- END REPeat
- END SELect
- EOF
- EXEC
- EXIT
- EXP
- FILL
- FILL$
- FLASH
- FORMAT
- GOSUB