First Steps in ProgrammingRISC OS Computers Martyn Fox

## Appendix 1 : Complete list of BASIC keywords

This appendix is for reference. It isn't meant to be read through from beginning to end - you would find it rather repetitive if you did. It lists all the keywords in the version of BBC Basic used in RISCOS 3 onwards. You are unlikely to use some of them, but they are all listed here for completeness.

You can use this table to go to the keyword you want. Clicking on any keyword heading will bring you back here.

### ABS

Gives the magnitude of its argument, i.e. turns negative numbers positive.

Example:

```  PRINT ABS(-5)
5

PRINT ABS(7)
7
```

### ACS

Gives the arc-cosine of the number following it in brackets.

Example:

```  ang=ACS(x)
```

In this example, ang is the angle in radians whose cosine is x. See DEG and RAD for conversion between radians and degrees.

Reads data from an analogue port, if fitted, or gives data on one of the machine's buffers.

Example:

```  num%=ADVAL(-1)
```

The keyboard buffer stores keypresses which have not been read by software. The variable num% in the above example will show the number of characters waiting in the buffer.

The following program will make the machine beep once every seven keypresses:

```  10 REPEAT
30   IF num%>6 THEN
40     VDU 7
50     *FX15
60   ENDIF
70 UNTIL FALSE
```

The command *FX15 flushes all buffers, i.e. empties them.

### AND

Applies a logical AND operation (see section 9), either to multiple statements following an IF keyword or to the individual bits of two numbers.

Examples:

```  num%=char% AND &DF
IF x%=2 AND y%=3 AND z%=4 THEN PROCdo_this
```

In the first example, &DF is used as a mask. Any bit in num% whose corresponding bit in &DF is a 1 has the same state as the equivalent bit in char%. Any bit corresponding to a 0 in &DF is forced to be a zero. The effect of this example is that bit 5 of num% is always zero. When applied to ASCII codes, this has the effect of turning lower case letters into capitals.

In the second example, PROCdo_this is only executed if x% equals 2 and y% equals 3 and z% equals 4.

### APPEND

Loads a file and adds it onto the end of the Basic program in memory.

Example:

```  APPEND "0.\$.Procs"
```

If the file contains a Basic program, its lines are automatically renumbered so that they are added onto the end of the first program.

### ASC

Gives the ASCII code of the first character in a string

Example:

```  char%=ASC("HELLO")
```

char% will be 72, which is the ASCII code for letter H.

### ASN

Gives the arc-sine of the number following it in brackets.

Example:

```  ang=ASN(x)
```

In this example, ang is the angle in radians whose sine is x. See DEG and RAD for conversion between radians and degrees.

### ATN

Gives the arc-tangent of the number following it in brackets.

Example:

```  ang=ATN(x)
```

In this example, ang is the angle in radians whose tangent is x. See and RAD for conversion between radians and degrees.

### AUTO

Puts line numbers on the screen automatically when entering a program, to save you having to type them in.

Examples:

```  AUTO
AUTO 100
AUTO 100,5
```

The first example will start a program with line 10, increasing the numbering in tens. The second will start numbering at line 100. This is useful if you had stopped entering a program after, say, line 90 (perhaps because you'd made a mistake) and you wanted to restart.

The third example will also start at line 100, but will number the lines in fives instead of tens.

To get out of AUTO mode, press Esc.

### BEAT

Gives the current beat value, used when dealing with sound.

Example:

```  count%=BEAT
```

The beat counter counts at a rate set by TEMPO until it reaches a number set by BEATS, when it is reset to zero. BEAT gives its current value.

See section 12 for an description of the sound system.

### BEATS

Either gives or sets the number that the beat counter counts up to, at a rate determined by TEMPO, when dealing with sound.

Examples:

```  BEATS 3000
PRINT BEATS
```

The first example sets the value of BEATS, the second reports it.

See section 12 for an description of the sound system.

### BGET#

Reads a single byte from an open file. An open file is one which has been opened with the command OPENIN, OPENOUT or OPENUP.

Example:

```  char%=BGET#handle%
```

The variable handle% is the file handle, which is a number given to the file when it is opened, using OPENIN, OPENOUT or OPENUP.

### BPUT#

Writes a byte or a string to an open file. An open file is one which has been opened with the command OPENUP or OPENOUT.

Examples:

```  BPUT#handle%,char%
BPUT#handle%,name\$
```

The variable handle% is the file handle, which is a number given to the file when it is opened, using either OPENUP or OPENOUT.

The first example writes a single byte to the file. Its position in the file is determined by the file pointer PTR#. The second example writes the ASCII codes of all the characters in the string to the file. This is followed by a Line Feed character (ASCII code 10) unless the name of the string is followed by a semi-colon(;). The value of PTR# is increased by one for each character written.

### BY

Can be added to MOVE, DRAW, POINT and FILL to define coordinates relative to the last position.

Example:

```  DRAW BY 100,0
```

will draw a horizontal line from the current graphics cursor position to a point 100 OS units to the right.

### CALL

Enters a machine code program from Basic.

Example:

```  CALL code%
```

The variable code% will have been set up to contain the address of the start of the machine code program, possibly by using the DIM command.

When the program is entered, the ARM or StrongARM processor's registers R0 to R7 are loaded from Basic variables A% to H% respectively.

### CASE

Used as part of CASE ... OF ... ENDCASE.

Example:

```  CASE a% OF
WHEN 1:PROCdo_this
WHEN 2:PROCdo_that
WHEN 3:PROCdo_also
OTHERWISE
PROCdo_something_else
ENDCASE
```

The value of the variable following CASE is checked against each of the numbers or variables following the WHEN keywords in turn. If a match is found, the program executes the rest of the line following the colon and then proceeds straight to ENDCASE, ignoring the lines in between (it will never execute more than one procedure). If a match has not been found by the time OTHERWISE is reached (which is optional), PROCdo_something_else is executed.

### CHAIN

LOAD and RUN a Basic program.

Example:

```  CHAIN "MyFile"
```

### CHR\$

Gives a one-character string determined by an ASCII code.

Example:

```  PRINT CHR\$(65)
A
```

### CIRCLE

Draws a circle.

Examples:

```  CIRCLE 600,500,200
CIRCLE FILL 400,300,200
```

The first example will draw a circle centred on x coordinate 600, y coordinate 500, with radius 200 OS units.

The second example will draw a solid circle with the same radius, centred on (400,300).

### CLEAR

Removes all variables. This is particularly useful if you want to redefine an array, whose dimensions cannot usually be altered once created.

This command dos not affect the Resident Integer Variables A% to Z%.

### CLG

Clears the graphics window to the graphics background colour.

This command also resets the graphics cursor to the graphics origin (0,0).

### CLOSE#

Closes a file which had been opened with OPENIN, OPENUP or OPENOUT.

Example:

```  CLOSE#handle%
```

The variable handle% is the file handle, which was assigned to the file when it was opened.

CLOSE#0 will close all files on the current filing system.

### CLS

Clears the text window to the text background colour.

This command also resets the text cursor to the top left-hand corner of the screen and resets COUNT to zero.

### COLOUR (also spelt COLOR)

Sets the text colour or alters the palette settings.

Examples:

```  COLOUR 1
```

sets the colour to logical colour 1 (usually red in 16-colour modes).

```  COLOUR 1,3
```

redefines logical colour 1 to be physical colour 3 (yellow). A subsequent COLOUR 1 command will produce yellow.

```  COLOUR 1,240,128,0
```

sets the proportions of red, green and blue in colour 1 to 240, 128 and zero respectively, to give orange.

### COS

Gives the cosine of the angle following it in brackets.

Example:

```  width%=length%*COS(angle)
```

### COUNT

Gives the number of characters printed since the last line feed was sent to the screen.

This function counts the number of characters sent to the screen by PRINT, INPUT or REPORT, but not VDU.

### CRUNCH

Used to remove REM statements and unwanted spaces from the current program. The action is determined by which bits are set in the number following CRUNCH:

 Bit Deleted 0 spaces before statements 1 spaces within statements 2 REMs (except in the first line, which may contain an embedded filename) 3 empty statements 4 empty lines

Examples:

```  CRUNCH 4
```

This has bit 2 set and will just delete REMs

```  CRUNCH 31
```

In hexadecimal notation, this would be CRUNCH &1F. This has all bits 0 - 4 set and so will delete everything shown above.

### DATA

Example:

```  READ x%,y%,z%
FOR n%=1 TO 3
NEXT
DATA 5,6,7
DATA Monday,Tuesday,Wednesday
```

The first line of this mini-program reads numbers 5, 6 and 7 into the values of x%, y% and z% respectively. The FOR ... NEXT loop in the following three lines sets day%(1), day%(2) and day%(3) to Monday, Tuesday and Wednesday respectively.

The data may be read as a number or a string, depending on the variable following the READ command.

### DEF

Used with PROC or FN to begin the definition of a procedure or function.

Examples:

```  DEFPROCdelay(time%)
DEFFNsize(x%)
```

You may put a space after DEF if you wish, but there must be no space between PROC or FN and the procedure or function name.

### DEG

Converts an angular measurement in radians into degrees.

Example:

```  twist=DEG(angle)
```

If angle is the size of an angle in radians, twist is its size in degrees.

One radian is approximately 57 degrees. There are 2*PI radians in a circle.

### DELETE

Used to delete lines of a program.

Example:

```  DELETE 100,150
```

This will delete all lines between and including lines 100 and 150.

It is not necessary to use DELETE when deleting one line. Just type the line number and press Return.

### DIM

Creates an array variable or a block of memory and defines its size.

Examples:

```  DIM month%(12)
DIM a%(5),b%(7,2),name\$(6)
DIM code% 100
```

The first example defines an array with 13 elements, called month%(0) to month%(12). The second example defines three arrays, the second of which is two-dimensional, having 24 elements, numbered b%(0,0) to b%(7,2).

The last example defines a block of memory 100 bytes in size, which may be used to store data or for the assembly of machine code. The value of the variable code% is the address of the first byte in the block.

### DIV

Performs whole number division, ignoring any remainder.

Example:

```  leap%=year% DIV 4
```

The variable year% is divided by 4, any fraction being rounded downwards, thus 15 DIV 4 gives 3 and 16 DIV 4 gives 4.

### DRAW

A command to draw a line from the last position of the graphics cursor to the coordinates given, which then become the new position of the graphics cursor.

Examples:

```  DRAW 800,400
DRAW BY 150,100
```

The first example draws a line from the previous graphics cursor position to (800,400). The second example includes the keyword BY, which takes the coordinates as being relative to the graphics cursor, not the graphics origin. If the two lines were together in a program, the second one would draw a line to (950,500).

### EDIT

Enters the Basic screen editor. This was available with RISCOS 2. It is now usual to write and edit Basic programs using a text editor such as !Edit.

### ELLIPSE

Draws an ellipse.

Examples:

```  ELLIPSE xpos%,ypos%,maj%,min%
ELLIPSE FILL xpos%,ypos%,maj%,min%,ang
```

The first example draws an ellipse centred on (xpos%,ypos%), with semi-major axis length maj% and semi-minor axis length min%.

The second example has the keyword FILL, so it draws a filled ellipse. The extra variable on the end of the command means that the ellipse is tilted with its semi-major axis at ang radians to the horizontal.

### ELSE

Used with IF ... THEN.

Example:

```  IF x%=2 PROCdo_this:PROCdo_this_too ELSE PROCdo_that
```

If x% equals 2 the program executes the remainder of the line up to the ELSE keyword. If x% does not equal 2, the program jumps to the ELSE keyword and executes the remainder of the line.

ELSE may also be used in multiple-line IF ... THEN structures:

```  IF x%=2 THEN
PROCdo_this
PROCdo_this_too
ELSE
PROCdo_that
ENDIF
```

ELSE is optional and is only needed if there is something to be executed when the expression following IF is not TRUE.

### END

(1) Marks the end of the program. END is not necessary when the program finishes on the last line, but is required when the main part is followed by procedures or functions. These will otherwise be executed as part of the main program, usually resulting in a 'not in a procedure' error message when the first ENDPROC is encountered.

(2) Gives the highest address used by the program.

Example:

```  PRINT END
```

### ENDCASE

Marks the end of a CASE ... OF structure.

Example:

```  CASE a% OF
WHEN 1:PROCdo_this
WHEN 2:PROCdo_that
WHEN 3:PROCdo_something_else
ENDCASE
```

The value of a% is compared with each of the numbers following the WHEN keywords in turn. When a match is found, the remainder of the line following the colon is executed. The rest of the structure is then ignored and the program jumps to whatever follows ENDCASE.

### ENDIF

Marks the end of a multiple-line IF ... THEN structure.

Example:

```  IF x%=y% THEN
PROCdo_this
IF a%=2 PROCdo_that
ENDIF
```

Multiple-line IF ... THEN structures are useful as they make it easy to use several IF statements at once. In this example, PROCdo_this is executed if x% equals y%, but PROCdo_that is only executed if x% equals y% and a% also equals 2.

### ENDPROC

Marks the end of a procedure and hands control back to the point where the procedure was called.

If the definition of the procedure included any parameters preceded by RETURN, their values are passed back to the corresponding global variables.

### ENDWHILE

Used with WHILE to construct a loop.

Example:

```  WHILE x%<5
PROCenter(x%)
x%+=1
ENDWHILE
```

### EOF#

Indicates whether or not the last byte in an open file has been reached.

Example:

```  handle%=OPENIN("filename")
REPEAT
char%=BGET#handle%
VDU char%
UNTIL EOF#handle%
CLOSE#handle%
```

This program opens a file and sends its contents to the screen, one byte at a time.

The variable handle% is the file handle, assigned to the file by the filing system when it is opened by OPENIN. Each time the REPEAT ... UNTIL loop is executed, one byte is read from the file using the BGET# keyword. EOF#handle% has the value FALSE until the final byte is read, when it changes to TRUE.

The file is closed at the end of the operation by CLOSE#handle%.

### EOR

Applies a logical exclusive-OR operation (see Section 9), either to two statements following an IF keyword or to the individual bits of two numbers.

Examples:

```  um%=char% EOR &20
IF x%=2 EOR y%=3 THEN PROCsend
```

The first example inverts the state of bit 5 of char%. This has the effect, with ASCII codes, of making capital letters lower case and vice versa.

In the second example, PROCsend is called if either x% equals 2 or y% equals 3, but not if both cases are true.

### ERL

Gives the line number where the last error was detected.

Example:

```  ON ERROR REPORT:PRINT " at line ";ERL
```

This line is useful if you run a program from the desktop while it is under development. Errors in this situation usually result in an error message without a line number, making it more difficult to debug the program.

### ERR

Error number of the last error.

Example:

```  ON ERROR IF ERR=17 PRINT "You pressed Escape, so goodbye!":END ELSE RE
PORT:PRINT " at line ";ERL:END
```

Pressing Esc is treated as an error - its error number is 17. This line prints a special message if you press Esc, but the usual message for any other errors.

### ERROR

(1) Used as part of ON ERROR to handle errors.

(2) Generates an error.

Example:

```  IF number%>5 THEN ERROR 1,"You must enter 5 or less"
```

If number% is greater than 5, the error handler is called. This might be a specially written line beginning with ON ERROR. The ERROR keyword in this example is followed by the error number, then the error message. The error handler can be written to detect this particular error number and act accordingly.

### EVAL

Gives the numeric equivalent of the string which follows it in brackets.

Example:

```  INPUT "What do you want me to work out",expr\$
PRINT EVAL(expr\$)
```

This program invites you to type in any expression that Basic could work out the value of, for example 3+2 or (4+5)/3. If you had already defined, say, a% to be 25, you could enter a%+2. The second line works out the answer and prints it.

### EXP

Gives the exponential of the number following it in brackets.

Example:

```  a=EXP(x)
```

a is e raised to the power of x, where e=2.718281828

### EXT#

Gives or alters the length of an open file.

Examples:

```  PRINT EXT#handle%
EXT#handle%=EXT#handle%+8
```

The first example prints the length of the file which had the file handle handle% assigned to it when it was opened by OPENIN, OPENOUT or OPENUP.

The second example increases the length of the file by eight bytes. The extra bytes are filled with zeros.

### FALSE

Gives the value zero.

Example:

```  done%=FALSE
```

A later line in the program may begin:

```  IF done% THEN
```

What follows will not be executed unless done% has in the meantime been changed from FALSE to TRUE.

### FILL

(1) Fills a shape when it is drawn.

Example:

```  RECTANGLE FILL 300,200,500,400
```

(2) Flood fills from a given point. Provided the point has the graphics background colour, the area around it is turned to the graphics foreground colour. The effect spreads out in all directions as far as any point which is not in the background colour, the edge of the graphics window or the edge of the screen.

Example:

```  FILL 300,200
```

### FN

Calls a function, or used with DEF to define a function.

Examples:

```  a%=FNsize(b%)
DEFFNsize(length%)
```

A function is similar to a procedure but it is used like a variable and ends by producing a value. In the first example, FNsize is called, passing a parameter from variable b%. On return, the number created in the function becomes the value of variable a%.

### FOR

Part of a FOR ... NEXT loop.

Example:

```  FOR n%=0 TO 5
PRINT n%
NEXT
```

This loop will print the numbers 0 to 5 in turn. When the loop is first executed, n% is given the value 0 and the program followed up to the NEXT command. Because n% is less than 5, the program returns to the FOR keyword, adds 1 to n% and executes the loop again, adding another 1 to n% each time it reaches NEXT. After the final run, when n% equals 5, the program carries on past the NEXT keyword.

The amount by which n% is increased each time round the loop can be altered by using the keyword STEP.

Examples:

```  FOR n%=0 TO 10 STEP 2
FOR i%=10 TO 1 STEP -1
```

In the first example, n% is increased by 2 each time the loop is executed and in the second, i% is decreased by 1 each time.

FOR ... NEXT loops may be nested, that is, put inside each other:

```  FOR n%=1 TO 10
FOR i%=0 TO 5
PRINT n%,i%
NEXT i%
NEXT n%
```

It is not necessary to put i% and n% after the two NEXT keywords as the program knows which FOR to go back to, but their inclusion does make the program easier to understand.

### GCOL

Sets graphics colours and PLOT actions.

Examples:

```  GCOL 3
GCOL plot%,col%
```

The first example selects colour 3 as the current graphics foreground colour. In a 16-colour mode this would normally be yellow unless colour 3 had been redefined by a COLOUR command. To change the graphics background colour, add 128 to the number. For a yellow background, for example, use GCOL 131.

The effect of a change of graphics background colour is seen when you clear the graphics window with CLG.

The second example has two numbers following GCOL. In this case, the colour is defined by the second number and the first one defines the PLOT action, that is how the colour should affect the screen:

 plot% action 0 set the screen to colour col% 1 OR the colour on the screen with col% 2 AND the colour on the screen with col% 3 EOR the colour on the screen with col% 4 Invert the colour on the screen 5 Don't change the screen at all 6 AND the colour on the screen with the inverse of col% 7 OR the colour on the screen with the inverse of col%

Add 8 to these colours to plot a sprite with a mask.

### GET

Gives the ASCII code of a character whose key is pressed.

Examples:

```  char%=GET
REPEAT UNTIL GET=13
```

In each case, the program will wait until it discovers that a key has been pressed. If a key is pressed before the program gets to this point, its ASCII code will be stored in the keyboard buffer and GET will read it immediately.

The second example makes the program wait until the Return key (ASCII code 13) has been pressed. If you want it to wait until you press any key, just use:

```  REPEAT UNTIL GET
```

To prevent the risk of a key being pressed in advance and stored in the buffer, you could precede this line with:

```  *FX15
```

which flushes (i.e. empties) all buffers.

### GET\$

Identical to GET, except that it gives a one-character string containing the character typed.

### GET\$#

Gets a string from an open file.

Example:

```  name\$=GET\$#handle%
```

The variable handle% is the file handle, which is a number given to the file when it is opened, using either OPENIN or OPENUP.

Characters are added to the string from the file, starting at the file pointer PTR# until a Line Feed, Return or zero is reached, the end of the file is encountered or the maximum string length of 255 characters is reached. The value of PTR# is increased so that it indicates the next byte in the file following the end of the string.

### GOSUB

Calls a subroutine by its line number.

Example:

```  GOSUB 2000
```

This example causes the program to jump to line 2000 and resume execution there until the command RETURN is reached. Control is then returned to the point immediately after the GOSUB command.

This command is provided mainly for compatibility with other versions of Basic. It is much better to use a procedure than a subroutine. A procedure is called by a name which, if well chosen, will give some indication of what it does. This makes it easier to follow the program, both at the point where the procedure is called and where its beginning is found in the listing.

Another important feature of procedures is the fact that you can pass variables to them through their parameters, which you cannot do with subroutines.

A program may easily be broken down into smaller units through the use of procedures, which can make it easier to understand. This is the essence of structured programming. A program broken down into subroutines, identified only by their line numbers, would be harder to follow.

### GOTO

Example:

```  GOTO 1000
```

Like GOSUB, this command is provided mainly for compatibility with other forms of Basic and its use is not generally recommended. It might be used to produce a continuous loop, jumping back to an earlier line, or to miss out some lines under certain conditions. The first case is better dealt with by using a REPEAT ... UNTIL loop and the second by an IF ... THEN ... ENDIF structure, as these show more clearly what is happening.

### HELP

Shows information about Basic or the current program.

Examples:

```  HELP
HELP A
HELP .
HELP PRINT
```

The first example will tell you when your copy of Basic was assembled, how much memory the program uses and how much is left over.

The second example shows a list of all the keywords beginning with 'A', or any other letter, while the third lists all the Basic keywords. Note that these lists are not strictly in alphabetical order. They have been rearranged slightly to improve minimum abbreviations, as these are checked against the list in order from the beginning. HELP A, for example, shows:

```  AND    ABS    ACS    ADVAL    ASC    ASN    ATN    AUTO    APPEND
```

Because AND comes at the beginning of the list, it is the keyword whose minimum abbreviation is A.. This is convenient because you are much more likely to type AND than ABS, ASC etc.

The fourth example gives you information about a particular keyword, in this case PRINT.

### HIMEM

The address of the highest byte in memory available to Basic.

Examples:

```  PRINT HIMEM
HIMEM=&A0000
```

### IF

Enables conditional execution of statements or lines.

Examples:

```  IF a%=b% THEN x%=2:PROCdo_this ELSE PROCdo_that
```

In most cases, THEN is not absolutely necessary, though its presence makes the line easier to understand.

The expression after the IF keyword is tested to see if it is TRUE, i.e. if a% does equal b%. If so, the remainder of the line up to ELSE is executed, otherwise the part of the line following ELSE is executed. In other words, if a% equals b%, then x% is given the value 2 and PROCdo_this is called. If a% doesn't equal b%, then PROCdo_that is called.

If there is nothing to be done if a% doesn't equal b%, the ELSE keyword is omitted.

Conditional execution may be applied over several lines:

```  IF a%=b% THEN
IF y%=4 x%=2
PROCdo_this
ELSE
PROCdo_that
ENDIF
```

The line beginning with IF has nothing following the THEN keyword, which indicates that conditional execution applies to the following lines, down to the ENDIF keyword.

Multiple line IF ... THEN structures are useful, partly because they allow a large chunk of programming to be conditionally executed and also because extra conditions can be applied to some lines. In this example, x% is only set equal to 2 if a% equals b% and y% also equals 4, but PROCdo_this is always called if a% equals b%.

Again, ELSE is only used if there is something to be done when the expression following the IF keyword is not true.

### INKEY

Gets an ASCII code for a character if a key is pressed.

Example:

```  char%=INKEY(100)
```

This keyword differs from GET in that it doesn't hold up the program until you press a key, but waits only up to a maximum time limit depending on the number in brackets, which is in centi-seconds. This example waits up to 1 second (100 centi-seconds). If a key is pressed during this time (or if a keypress has been stored in the keyboard buffer), the value of char% becomes the ASCII code of the key, otherwise char% becomes -1.

This is a useful way of building a time delay into a program, particularly if it can be cut short by pressing a key. You could, for example, display a short message on the screen with an instruction to 'press any key' when it has been read, but decide that 10 seconds is ample time to read it and the program should proceed after that time anyway. Use the following commands:

```  *FX15
x%=INKEY(1000)
```

The first line flushes all the buffers to ensure that there isn't already a keypress in the keyboard buffer and the second line waits for up to 10 seconds. If a key is pressed in this time, the program proceeds immediately. The variable x% is given the ASCII code for the key pressed, or -1 if no key was pressed. If it doesn't matter which key was pressed, x% will be a dummy variable which is not used again.

If INKEY is followed by a negative number, the operating system checks to see if a particular key is pressed and returns TRUE or FALSE, depending on whether or not it's pressed. All keys have negative INKEY numbers, including the Shift, Ctrl and Alt keys and the mouse buttons, but a list of them is outside the scope of this guide.

### INKEY\$

Behaves in the same way as INKEY, except that it gives a one-character string containing the character whose key was pressed.

Where INKEY would give -1, INKEY\$ gives a null string, i.e. a string with no characters.

### INPUT

Reads in a number or string from the keyboard and assigns it to a variable.

Examples:

```  INPUT length%
INPUT name\$
INPUT a%,b%,c%,d%
```

The first two examples cause a question mark to be displayed with the cursor to the right of it. The third one displays the text in quotes. If the text is followed by a comma, a question mark follows it on the screen, otherwise it is left out.

The fourth example gives four question marks, prompting for four variables.

If you type in a string containing leading spaces or commas, INPUT will ignore the leading spaces and first comma and everything after it. If you want to be able to enter a string which may contain these, use INPUT LINE instead of INPUT.

### INPUT#

Gets information from an open file. An open file is one which has been opened with the command OPENIN, OPENUP or OPENOUT.

Example:

```  INPUT#handle%,title\$,length%
```

The variable handle% is the file handle, which is a number given to the file when it is opened, using OPENIN, OPENUP or OPENOUT.

The command in this example expects to receive a string from the file, followed by a number.

### INSTALL

Loads a Basic file containing a library of functions or procedures into memory.

Example:

```  INSTALL "0.\$.Procedures"
```

The file is loaded into the top of available memory and HIMEM is reduced to below the point where it starts. If a procedure is called which isn't in the main program, Basic looks for it in the library.

The installed library remains in memory until you QUIT from Basic.

Library files must not contain references to line numbers such as GOTO or GOSUB. Basic's DATA pointer may be reset by a command such as RESTORE+1. It is safest to use only local variables, used within the function or procedure in question.

A library file should include a description of what it contains in the first line, as this will be listed by the LVAR command.

Example:

```  10 REM > Lib_file1 - Contains graphics routines
```

### INSTR

Finds the position of one string within another.

Example:

```  a\$="Hello mum"
b\$="lo"
PRINT INSTR(a\$,b\$)
4
```

The program looks for the string lo within the longer string Hello mum and finds it, starting with the fourth letter, so it gives the answer 4. If the second string isn't present within the first one, INSTR gives a value of zero .

### INT

Gives the integer, or whole number, part of a number.

Example:

```  PRINT INT(4.5)
4
```

The number is rounded down to the nearest whole number equal to or below it.

### LEFT\$

Gives or alters the left-hand part of a string.

Examples:

```  a\$=LEFT\$(name\$,3)
b\$=LEFT\$(name\$)
LEFT\$(name\$,3)="Abc"
LEFT\$(name\$)=c\$
```

In the first example, a\$ is set to the first three characters of name\$. The second example doesn't have a second number or variable in brackets and b\$ is set to all of name\$ except for the final character.

In the third example, the first three characters of name\$ are replaced by Abc, while in the fourth example, however many characters there are in c\$ replace the same number of characters at the beginning of name\$.

### LEN

Gives the length of a string, i.e. the number of characters it contains.

Example:

```  a\$="ABCDE"
PRINT LENa\$
5
```

### LET

Optional keyword used when assigning a value to a variable, included mainly for compatibility with other versions of Basic.

Example:

```  LET x%=a%+b%
```

This has exactly the same meaning as:

```  x%=a%+b%
```

### LIBRARY

Loads a Basic file containing functions or procedures into memory, allowing its contents to be called from the main program.

Example:

```  LIBRARY "0.\$.Procs"
```

There are two differences between LIBRARY and INSTALL:

• INSTALL cannot be included in a program but must be called from immediate mode. LIBRARY can be included in a program listing.
• INSTALL loads a file into a part of the memory not used by the current program and it stays there until you exit from Basic with QUIT. LIBRARY loads the file into a part of the memory used by the program. If you type NEW or load a new program, the library file will disappear, along with the old program.

LINE (1) Draws a line between two points.

Example:

```  LINE 300,200,600,800
```

This example draws a line between coordinates (300,200) and (600,800). The graphics cursor position ends up at (600,800)

(2) Used with INPUT to form LINE INPUT and INPUT LINE, both of which have the same meaning.

This combination of keywords allows you to type in a string containing leading spaces and commas. If you use INPUT on its own, leading spaces, the first comma and everything after it will be ignored.

### LIST

Displays a listing of the program.

Examples:

```  LIST
LIST 100,600
LIST IF name\$
```

The first example lists the entire program. If the program is long, it will fly up the screen too fast for you to read. You can slow it down by holding down Ctrl. Better still, you can put the screen into 'page' mode by pressing Ctrl-N before you type LIST. This will stop the screen scrolling by more than the number of lines that can be displayed at once.

To see some more of the program, press Shift (it's easiest if you hold down Ctrl as you do so, otherwise you may allow some lines to scroll off the top of the screen before you release Shift).

To stop a listing before you reach the end, press Esc. To cancel page mode, press Ctrl­O.

The second example lists part of the program, in this case from lines 100 to 600 inclusive.

The third example is a conditional listing and shows all lines containing the string following IF, in this case all those containing a reference to the variable name\$. Note that there isn't a space between IF and name\$. If you include a space, it will be counted as part of the string and a line will only be listed if it contains the contents of name\$, preceded by a space.

### LISTO

Controls the way the listing appears on the screen.

Example:

```  LISTO 3
```

The appearance of the listing depends on the setting of the various bits of the number following LISTO:

 Bit Purpose 0 Puts a space after the line number 1 Indents FOR ... NEXT, IF ... THEN ... ENDIF and other structures 2 Splits lines at colons 3 Does not list line numbers 4 Prints keywords in lower case

The number 3 in the example has bits 0 and 1 set. This means that a space is inserted after the line number and structures are indented.

If you type in a program when LISTO is not zero, any leading spaces on the lines will be stripped off.

### LN

Gives the natural logarithm of the number or variable following it in brackets, that is, the logarithm to the base 'e' (2.718281828).

Example:

```  PRINT LN(size)
```

Loads a program into memory at the current setting of PAGE.

Example:

```  LOAD "0.\$.MyProg"
```

Any existing program in memory is discarded, along with its variables. The Resident Integer Variables (A% - Z%) are not affected.

### LOCAL

(1) Creates local variables in a procedure or function.

Example:

```  DEFPROCsize
LOCAL length%,width%,height%
```

The variables length%, width% and height% are newly created and exist only within the procedure or function. The values of any other variables with the same names outside the procedure or function (known as global variables) are not affected by what happens inside it.

When local variables are created, they are given a value of zero in the case of numeric variables, and the null string in the case of strings.

(2) Used with ERROR to produce LOCAL ERROR.

When you define an error handler, using ON ERROR ... , any previous error handler is normally forgotten by Basic. You can prevent this happening by preceding the new error handler definition with LOCAL ERROR. Basic remembers the previous error handler and will revert to it if you use the command RESTORE ERROR.

You need LOCAL ERROR if you define a local error handler within a function or procedure using ON ERROR LOCAL (see ON).

Example:

```  DEFFNopen_file(filename\$)
LOCAL ERROR
ON ERROR LOCAL REPORT:=0
handle%=OPENIN(filename\$)
=handle%
```

This function tries to open a file whose filename is passed to it as a parameter and ends by returning the file handle to the main program. If it fails to open the file, the error doesn't stop the program; it simply prints the error message (the REPORT command) and returns to the main program, giving a value of zero. Because LOCAL ERROR was used within a function or procedure, it isn't necessary to use RESTORE ERROR. This happens automatically at the end of the function.

### LOG

Gives the logarithm to the base 10 of the number or variable following it in brackets.

Example:

```  PRINT LOG(size)
```

### LOMEM

The address in memory where storage of the program's variables starts.

Examples:

```  PRINT LOMEM
LOMEM=TOP+&800
```

The second example sets LOMEM to be &800 (2048) bytes above the top of the program, reserving the memory in between for some special purpose. You can only do this in a program before you create any variables. LOMEM is reset to TOP when you type RUN.

### LVAR

Lists all the variables used in a program, procedures and functions used and the first line of any libraries loaded.

Note: Apart from the Resident Integer Variables (A% - Z%), which are always present, this information only shows what has actually been encountered while running the program.

### MID\$

Gives or alters the middle portion of a string.

Examples:

```  a\$=MID\$(name\$,2,3)
b\$=MID\$(name\$,2)
MID\$(name\$,2,3)="Abc"
MID\$(name\$,2)=c\$
```

In the first example, a\$ is set to a string consisting of three characters within name\$, beginning with the second one. The second example doesn't have a third number or variable in brackets and b\$ is set to all of name\$ from the second character onwards.

In the third example, the three characters of name\$ beginning with the second one are replaced by "Abc", while in the fourth example, however many characters there are in c\$ replace the same number of characters in name\$, beginning with the second one.

### MOD

Gives a remainder, following whole number division.

Example:

```  PRINT 17 MOD 7
3
```

Whole number division of 17 by 7 gives 2, with a remainder of 3.

### MODE

Sets the screen mode or gives the current mode.

Examples:

```  MODE 12
PRINT MODE
```

The first example changes screen mode to mode 12. This resets everything connected with the VDU to its default settings. The screen is cleared to black, the text cursor is set to the top left-hand corner and the graphics cursor to the bottom left-hand corner (0,0) The text and graphics windows are both set to cover the full screen.

The second example prints the current screen mode.

### MOUSE

Gives the current mouse position and the state of its buttons, turns the pointer on and off and sets various other parameters connected with the mouse.

Examples:

```  MOUSE xpos%,ypos%,buttons%
MOUSE ON
MOUSE OFF
MOUSE COLOUR 1,255,0,0
MOUSE STEP 4,1
MOUSE RECTANGLE 200,200,1000,800
```

The first example assigns the x and y coordinates of the mouse pointer to variables xpos% and ypos%. The bits of buttons% are determined by the state of the buttons:

 Bit Purpose 0 Right-hand button pressed 1 Middle button pressed 2 Left-hand button pressed

If no button is pressed, buttons% will be zero. If the left-hand (Select) button is pressed, buttons% will have a value of 4.

The second and third examples turn the pointer on and off and the fourth sets its colour. There are three colours available to the mouse pointer - the default pointer uses two of them, 1 for the outer part of the arrow and 2 for the inner section.

This example sets the outer part of the pointer to bright red.

The fifth example sets the speed at which the pointer will move across the screen when the mouse is moved. In this example, the pointer will move rapidly (speed 4) horizontally, but slowly (speed 1) vertically. If MOUSE STEP is followed by one number, it is applied to both directions.

The last example defines a rectangle which the pointer may not go outside.

### MOVE

Moves the graphics cursor to a new position without drawing a line on the way.

Example:

```  MOVE 600,500
```

This example moves the graphics cursor to a point roughly in the middle of the screen. If it is followed by a command such as DRAW 800,700, the result will be a line from (600,500) to (800,700).

If MOVE is followed by BY, the coordinates given are taken to be relative to the previous graphics cursor position.

### NEW

Effectively removes the current Basic program from memory.

This command enables you to start entering a new program without having to delete the lines of the old one, but it doesn't actually remove it from memory. If you type NEW, then change your mind before you start entering a new program, you can recover what was there by typing OLD.

### NEXT

Part of a FOR ... NEXT loop.

Examples:

```  FOR n%=0 TO 3
PRINT name\$(n%)
NEXT n%

FOR n%=0 TO 4
FOR i%=0 TO 3
NEXT i%,n%
```

The first example is a simple loop in which n% is increased by 1 each time the loop is executed. The variable name after NEXT is usually omitted, but its presence makes the program a little clearer to follow and will also produce an error message if you have several loops inside each other (they are said to be nested) and their NEXT commands come up in the wrong order.

The second example shows how it's possible to have two or more nested FOR...NEXT loops. The inner loop is executed four times for each time round the outer loop. These two loops could end with two NEXT commands, but the last line in this example ends both loops at the same time.

### NOT

Changes the state of a variable from TRUE to FALSE or vice versa, or inverts all the bits of a number.

Examples:

```  IF NOT done% THEN PRINT "Another go?"
x%=NOT y%
```

The first example is the same as typing:

```  IF done%=FALSE THEN PRINT "Another go?"
```

The program will only execute the PRINT command if the expression that follows the IF keyword is TRUE. If done% is FALSE, NOT done% is TRUE. Similarly, if done% is FALSE, the expression done%=FALSE is true, because the parts of the expression on each side of the equals sign are the same.

In the second example, each bit of x% is given the opposite state to the corresponding bit of y%. If y% is zero, x% is -1 and if y% equals 1, x% is -2.

The reason for this apparently strange state of affairs is that zero in binary consists of 32 noughts:

0000 0000 0000 0000 0000 0000 0000 0000

NOT zero, therefore, is:

1111 1111 1111 1111 1111 1111 1111 1111

or &FFFFFFFF in hexadecimal, which is usually taken to be -1 (see Section 9).

Similarly, 1 is:

0000 0000 0000 0000 0000 0000 0000 0001

so NOT 1 is:

1111 1111 1111 1111 1111 1111 1111 1110

or &FFFFFFFE, which is -2.

### OF

Used as part of CASE ... OF ... ENDCASE.

See CASE.

### OFF

Turns off the text cursor, or used as part of other commands.

Examples:

```  OFF
TRACE OFF
SOUND OFF
MOUSE OFF
ON ERROR OFF
```

The first example turns off the text cursor. You can turn it on again by typing ON. It will also reappear if you change screen mode of perform cursor editing.

The following three examples turn off tracing of the current program (see TRACE), all sound output (use SOUND ON to turn it on again) and the mouse pointer.

The final example disables the program's own error handler and reverts to Basic's own way of dealing with errors. If you write a program with a long and complicated error handler routine, it might be advisable to insert ON ERROR OFF while testing it, in case the error handler itself contains an error, which could put you in an endless loop with the error handler calling itself!

### OLD

Recovers a program if you type NEW, then change your mind.

This command will only work provided you have not entered any new program lines or created any variables in immediate mode, as these will start to overwrite your old program.

### ON

Turns on various functions, provides conditional branching or sets up an error handler.

Examples:

```  ON
SOUND ON
MOUSE ON
ON num% GOTO 1000,2000,3000 ELSE 4000
ON num% PROCthis,PROCthat,PROCother ELSE PROCsomething_else
ON ERROR CLOSE#0:REPORT:PRINT " at line ";ERL:END
ON ERROR LOCAL PRINT "You can't do that";ENDPROC
```

The first three examples turn on the text cursor, sound output and mouse pointer respectively.

The third example examines the value of the variable num% following ON. In this case, if num% equals 1, the program jumps to line 1000; if it is 2, it jumps to line 2000 and so on. If num% is less than 1 or greater than the number of line numbers following ON, the program jumps to line 4000.

If you replace the GOTO with a GOSUB, the program will return to the line following the ON command when it encounters a RETURN.

The fourth example works in the same way as the third one, only by calling procedures. This is preferable to jumping to line numbers as it makes the program more structured and easier to follow.

You may find it more convenient to use a CASE...OF...ENDCASE structure to do this job.

Example 6 sets up an error handler routine. This one is similar to Basic's own error handler, except that it closes any files that may be open. If a program opens a file with OPENIN, OPENUP or OPENOUT, it is advisable to include a CLOSE command in the error handler, otherwise a file may be left open if an error occurs.

If an error occurs within a loop, or a function or procedure, Basic jumps to the error handler forgetting about the structure where the error occurred. To remain within the procedure or loop after the error handler has done its work, use ON ERROR LOCAL, as shown in the final example.

Any error that follows this command makes the program jump to this error handler without forgetting that it's in a procedure. In order that the main error handler can take over again after the program leaves the procedure, ON ERROR LOCAL should be preceded by LOCAL ERROR (see LOCAL).

### OPENIN

Opens an existing file for read-only access.

Example:

```  handle%=OPENIN("0.\$.MyFile")
```

The filename, or the pathname as shown in this example, is only used when opening the file. Once the file is open, it is always referred to by its file handle, which is the number given to variable handle%. Keywords such as BGET#, EXT# and EOF# which operate on files refer to the file by its handle.

### OPENOUT

Opens a new file which is initially zero bytes long. If a file with the same filename already exists, it is deleted and a new one created. Once the file has something in it, it can be read as well as written to.

Example:

```  handle%=OPENOUT("0.\$.MyFile")
```

The filename, or the pathname as shown in this example, is only used when opening the file. Once the file is open, it is always referred to by its file handle, which is the number given to variable handle%. Keywords such as BGET#, EXT# and EOF# which operate on files refer to the file by its handle.

### OPENUP

Opens an existing file for read or write access.

Example:

```  handle%=OPENUP("0.\$.MyFile")
```

The filename, or the pathname as shown in this example, is only used when opening the file. Once the file is open, it is always referred to by its file handle, which is the number given to variable handle%. Keywords such as BGET#, EXT# and EOF# which operate on files refer to the file by its handle.

### OR

Applies a logical OR operation (see Section 9), either to multiple statements following an IF keyword or to the individual bits of two numbers.

Examples:

```  char%=num% OR &30
IF x%=2 OR y%=3 OR z%=4 THEN PROCdo_this
```

In the first example, any bit in either num% or &30 which is a 1 forces the corresponding bit in char% to be a 1. If num% is 5, char% will be &35.

This example derives an ASCII code from a number. If num% is between 0 and 9, char% will be its ASCII code. See Sections 8 and 9 for a full description of ASCII codes.

In the second example, PROCdo_this is only executed if x% equals 2 and y% equals 3 and z% equals 4.

### ORIGIN

Moves the graphics origin.

Example:

```  ORIGIN 600,500
```

This example moves the graphics origin to a point close to the middle of the screen. All MOVE, DRAW, RECTANGLE etc. commands work with coordinates relative to this point.

Note, though, that the graphics cursor position is not moved by the ORIGIN command. If, for instance, you type:

```  MOVE 50,50
ORIGIN 600,500
DRAW 100,100
```

a line will be drawn from the old (50,50), close to the bottom left-hand corner of the screen, to the new (100,100), a little above and to the right of the centre.

### OSCLI

Generates a string and passes it to the Command Line Interpreter (CLI).

This is the part of the operating system that deals with star commands. Because a star command is passed directly to the CLI without being handled by Basic, you can't include references to any Basic variables in it as the CLI will not understand them.

Example:

```  OSCLI ("Load "+fname\$+" "+STR\$~buf%)
```

It is possible to load a file into memory with a command such as:

```  *Load MyFile A000
```

where A000 is the address in hexadecimal notation of the first byte of the buffer, i.e. the part of the memory where you want the file to go. Well-written programs are independent of absolute memory addresses of this sort and make no reference to them. Instead, a block of memory to be used as a file buffer can be defined using the DIM statement and the program will only know the address as the name of a variable.

In this example, we're also using a string variable to contain the filename. We can't type the filename directly into a star command when we write the program because we may not know it. The program might ask you to enter it, perhaps using the INPUT command, and then load the appropriate file.

This example creates a string within the brackets following the OSCLI keyword. The first part consists of the command Load in quotes with a space on the end, followed by the filename, then another space. The next part creates the address. The expression STR\$~buf% creates a string containing the value of num% and the tilde (~) character puts it in hexadecimal form. If the filename in name\$ is '0.\$.MyFile' and the value of buf% is, say, &A456, the entire string sent to the Command Line Interpreter will be:

```  Load 0.\$.MyFile A456
```

### OTHERWISE

Used as part of a CASE ... OF ... ENDCASE structure.

Example:

```  CASE a% OF
WHEN 1:PROCdo_this
WHEN 2:PROCdo_that
WHEN 3:PROCdo_also
OTHERWISE
PROCdo_something_else
ENDCASE
```

If a% is 1, 2 or 3, the appropriate procedure is executed. In all other cases, the program executes PROCdo_something_else.

The use of OTHERWISE is optional. You only need it when there is something to be done if none of the WHEN conditions are met.

### OVERLAY

Sets an array of filenames for overlay function and procedure libraries.

Example:

```  DIM lib_file\$(3)
lib_file\$()="filename1","filename2","filename3","filename4"
OVERLAY lib_file\$()
```

The second line of the example puts one filename into each element of array lib_file\$(). Each file contains a directory of functions and procedures, as used by the INSTALL and LIBRARY commands.

When Basic encounters the OVERLAY keyword, it checks the sizes of all the files in the array and reserves enough memory to hold the largest. If a call is encountered to a function or procedure not in the program, Basic first checks any libraries loaded with INSTALL or LIBRARY. If it cannot find what it is looking for, it goes through each file in the array in turn, loading the appropriate file when it finds it.

If there is a subsequent call to a function or procedure in another file, that file is loaded in place of the original.

### PAGE

The address in memory where a stored Basic program starts.

Examples:

```  PRINT ~PAGE
PAGE=&C000
```

By using the second example, it is possible to have more than one program stored in memory at the same time. You can change the value of PAGE and load a new program from disc. To switch between programs, set PAGE to the appropriate value and type OLD.

PAGE must be word-aligned, that is, divisible by 4.

### PI

Basic's way of writing the Greek letter which is used to describe the ratio between the diameter and circumference of a circle.

Example:

```  PRINT PI
3.141592653
```

### PLOT

Moves the graphics cursor or draw on the screen in a particular way, determined by the PLOT code.

See Appendix 3 for a full list of PLOT codes.

Example:

```  PLOT 85,400,300
```

This example draws a filled triangle between (400,300) and the previous two positions of the graphics cursor.

### POINT

(1) Plots a single point on the screen.

Example:

```  POINT 900,800
```

This will plot a point at (900,800) and move the graphics cursor to that position.

If POINT is followed by BY, the coordinates are taken to be relative to the last position of the graphics cursor.

(2) Gets the logical colour of a pixel.

Example:

```  col%=POINT(500,400)
```

The value of col% will be the logical colour of the pixel at (500,400). If the screen is in a 256-colour mode, this will be a number between 0 and 63, describing the colour but not the tint. The tint number can be checked by typing:

```  tint%=TINT(500,400)
```

### POS

Gives the horizontal position of the text cursor.

Example:

```  x%=POS
```

The value of x% will be the number of columns in from the left-hand side of the screen (or text window, if set) the text cursor is located.

### PRINT

Displays on the screen.

Example:

```  PRINT "The answer is ";ans%
```

The first part of the remainder of the line following PRINT is in quotes and appears on the screen exactly as shown. The value of variable ans% is then added. If the semi-colon (;) were not present, this number would be right-justified, meaning that spaces would be added before it, making a total of 10 spaces and digits (excluding the space at the end of the string in brackets). The presence of the semi-colon means that this does not happen.

If ans% were preceded by a tilde (~), its value would be shown in hexadecimal notation.

To print several right-justified variables, separate them with commas.

An apostrophe (') will cause a new line to be started.

### PRINT#

Sends information to an open file. An open file is one which has been opened with the command OPENUP or OPENOUT.

Example:

```  PRINT#handle%,title\$,page_no%
```

The variable handle% is the file handle, which is a number given to the file when it is opened, using either OPENUP or OPENOUT.

The command in this example sends a string to the file, followed by a number. Both are stored in a particular way and may be read back in order using INPUT#.

### PROC

Used in calling and defining a procedure.

Examples:

```  IF x%=2 PROCsize(length%)
DEFPROCsize(l%)
```

In the first example, PROCsize is called if x% equals 2. The variable length% is passed to it as a parameter.

The second example is located at the start of the definition of the procedure. In this case, the procedure is defined as having one parameter, referred to as l%. Within the procedure, l% is treated as a local variable, which makes it totally separate from any other variable with the same name in the main program (a global variable).

There must not be a space between PROC and the procedure name in either of these uses, but you can put a space between DEF and PROC.

### PTR#

Gives the position of the pointer of an open file. An open file is one which has been opened with the command OPENIN, OPENOUT or OPENUP.

The pointer is used by commands such as BGET# and BPUT# which read from or write to a file and determines the position in the file where the operation is performed. In this way, random access to a file is possible.

Example:

```  PTR#handle%=10
```

The variable handle% is the file handle, which is a number given to the file when it is opened, using either OPENIN, OPENOUT or OPENUP.

This example moves the pointer to a position 10 bytes in from the start of the file.

### QUIT

Shuts down Basic.

When this happens, you will be left with the star prompt, which simply allows you to enter star commands. If you had originally started Basic by running a file from the desktop, pressing Return will take you back to the desktop in the state it was when you left it, otherwise type:

```  *Desktop
```

to start up the desktop, or:

```  *Basic
```

to restart Basic.

Converts an angular measurement in degrees into radians.

Example:

```  twist=RAD(angle)
```

If angle is the size of an angle in degrees, twist is its size in radians.

One radian is approximately 57 degrees. There are 2*PI radians in a circle. Trigonometric functions, such as SIN, COS and TAN work with angles expressed in radians.

Reads information from a DATA statement.

Example:

```  READ length%,width%
.......
DATA 5,7
```

When the first READ command is encountered, Basic looks for the first DATA keyword in the program (unless it has been told to look elsewhere by RESTORE). Each variable following READ is given a value taken from the number(s) or string(s) following DATA. At the end of the READ operation, Basic remembers where it took the last DATA from (using its Data Pointer) and takes more DATA from the point following it, if it encounters any more READ commands.

### RECTANGLE

Draws a rectangle on the screen, copies or moves a rectangular portion of the screen to another position or limits the movement of the mouse pointer.

Examples:

```  RECTANGLE 300,200,500,400
RECTANGLE 100,100,400,300 TO 600,500
RECTANGLE FILL 100,100,400,300 TO 600,500
MOUSE RECTANGLE 200,200,1000,800
```

The first example draws a rectangle whose bottom left-hand corner is at (300,200) and which is 500 OS units wide and 400 units high. If RECTANGLE is followed by FILL, the rectangle is filled with the graphics foreground colour.

RECTANGLE leaves the graphics cursor in the bottom left-hand corner but RECTANGLE FILL leaves it in the top right-hand corner.

The second example copies a rectangular section of the screen. The coordinates are defined as in the first example, with the bottom left-hand corner at (100,100), the width 400 units and the height 300 units. The bottom left-hand corner of the copy is at 600,500.

The third example is the same as the second except that the original rectangle is cleared to the graphics background colour, in other words, RECTANGLE ... TO copies a rectangle, RECTANGLE FILL ... TO moves it.

The final example limits the movement of the mouse pointer to a rectangle whose bottom left-hand corner is at (200,200) and whose top right-hand corner is at (1000,800).

### REM

Short for REMark. The remainder of the line is ignored by Basic.

Example:

```  REM This is a comment to explain the program
```

This enables you to put comments in the program to explain its workings.

The exception is a REM in the first line of the program which contains an embedded filename.

Example:

```  10 REM > MyFile
```

The REM keyword must be in the first line and be followed by a 'greater than' symbol (>), then by the filename. It is then only necessary to type SAVE to save the program.

### RENUMBER

Renumbers the program lines.

Examples:

```  RENUMBER
RENUMBER 500
RENUMBER 600,5
```

The first example simply renumbers the program with line numbers starting at 10 and increasing in tens. The second example begins at 500, also increasing in tens, while the final one starts at 600 and increases in fives.

Basic checks for GOTOs, GOSUBs and any other references to line numbers and changes them accordingly.

### REPEAT

Used to begin a REPEAT ... UNTIL loop.

Example:

```  REPEAT
char%=GET
UNTIL char%=13
```

This loop waits until you press Return by checking to see if the ASCII code produced by GET equals 13. If what follows UNTIL is not TRUE, the program jumps back to REPEAT.

By using UNTIL FALSE, a loop can be made to repeat indefinitely until an error occurs or Esc is pressed.

Several REPEAT ... UNTIL loops can be nested, that is, put inside one another.

### REPORT

Displays the error message connected with the last error encountered.

Example:

```  ON ERROR REPORT:PRINT "at line ";ERL:END
```

REPORT starts on a new line. If you want more flexibility than this, you can use REPORT\$ instead. This is a string variable containing the error message which can be used in the same way as any other string variable, for example:

```  ON ERROR PRINT "You had a " REPORT\$ " at line ";ERL:END
```

### RESTORE

Sets the DATA pointer or retrieves the previous error handler.

Examples:

```  RESTORE
RESTORE 500
RESTORE +1
RESTORE ERROR
```

The DATA pointer marks the point in the program that Basic takes data from in READ operations.

The first example resets the pointer to the first DATA statement in the program and the second sets it to the DATA statement on line 500. This operation can be made independent of line numbering by using the third example which sets the pointer to the first DATA statement following the line on which the RESTORE command is given.

The final example is used in conjunction with a LOCAL ERROR command. This command remembers the current error handler so that it isn't forgotten when a new error handler is set up, using ON ERROR ... .

RESTORE ERROR cancels the new error handler and restores the previous one.

If you use LOCAL ERROR within a procedure and set up an error handler with ON ERROR LOCAL, you will not need RESTORE ERROR at the end of the procedure, as this happens automatically.

### RETURN

(1) Marks the end of a subroutine

(2) Indicates two-way value passing in a procedure parameter.

Examples:

```  RETURN
DEFPROCget_coords(RETURN xpos%,RETURN ypos%)
```

A subroutine is called using GOSUB and referred to by the number of its first line (see GOSUB). RETURN, as in the first example, makes the program jump back to the point after the GOSUB command.

The second example shows the first line of a procedure which might be used to get the x and y coordinates of a point. Because it has to return two numbers, we can't use a function for this job. Because the procedure definition has two parameters, xpos% and ypos%, the command that calls the procedure must include two global variables as parameters, for example:

```  PROCget_coords(left_side%, top_side%)
```

Normally, left_side% would pass its value to xpos% and top_side% its value to ypos%, but nothing would be passed back the other way when the procedure hands back to the main program. Because both xpos% and ypos% are preceded by RETURN in the procedure definition, however, their final values when the procedure finishes are passed back to become the new values of left_side% and top_side%.

A variable must usually already exist when you use it as a parameter to call a procedure, otherwise it has no value to pass to the procedure and you will get an Unknown or missing variable error. Because xpos% and ypos% have RETURN in front of them, however, it's not necessary for left_side% and top_side% to already exist when you use them to call the procedure.

### RIGHT\$

Gives or alters the right-hand part of a string.

Examples:

```  a\$=RIGHT\$(name\$,3)
b\$=RIGHT\$(name\$)
RIGHT\$(name\$,3)="Abc"
RIGHT\$(name\$)=c\$
```

In the first example, a\$ is set to the last three characters of name\$. The second example doesn't have a second number or variable in brackets and b\$ is set to just the final character of name\$.

In the third example, the last three characters of name\$ are replaced by Abc, while in the fourth example, the characters of c\$ replace the same number of characters at the end of name\$.

### RND

Generates a pseudo-random number.

Examples:

```  x%=RND
x=RND(1)
xpos%=RND(10)
x%=RND(-2)
```

A pseudo-random number generator is one which actually follows a pattern when generating numbers, but one so complicated that the numbers may be regarded as being random.

The first example produces a number between -2147483648 and 2147483647, or, in hexadecimal notation, between 0 and &FFFFFFFF.

The second example, with 1 in the brackets, generates a number between 0 and 0.999999999.

The third one, with a number greater than 1, generates a whole number, in this case between 1 and 10. If you wanted a random number between, say, 4 and 10, you could get it with:

```  x%=RND(7)+3
```

The random number will lie between 1 and 7 so the total will be between 4 and 10.

The final example, with -2 in brackets, will give -2. This may not seem very random, but it has also reset the random number generator. If you do this more than once, using the same negative number each time, then produce numbers between the same limits each time, you will get the same sequence of 'random' numbers. This can be useful while developing a program.

### RUN

Executes the program in memory.

Any existing variables other than the Resident Integer Variables (A% to Z%) are cleared before the program starts.

### SAVE

Saves the program.

Examples:

```  SAVE
SAVE "MyProg"
```

The first example can only be used if the first line of the program contains an embedded filename, for example:

```  10 REM > MyProg
```

The second example will save the program, using the filename 'MyProg' in the Currently Selected Directory. This will normally be the root directory of the disc in your floppy drive unless you have changed it.

The third example specifies the pathname of the file. In this case, the program is saved in a directory called 'Progs' which itself is situated in the root directory of the hard disc.

### SGN

Gives the sign (positive or negative) of the value following it in brackets.

Example:

```  sign%=SGN(num%)
```

If num% is positive, sign% will be 1.

If num% is zero, sign% will be 0.

If num% is negative, sign% will be -1.

### SIN

Gives the sine of the angle following it in brackets.

Example:

```  height%=length%*SIN(angle)
```

### SOUND

Generates a sound or turns sound output on or off.

Examples:

```  SOUND chan%,vol%,pitch%,dur%
SOUND chan%,vol%,pitch%,dur%,delay%
SOUND ON
SOUND OFF
```

The first two examples generate a sound. Variable chan% is the channel number, vol% the amplitude, pitch% the pitch and dur% the duration. The second example allows for a delay, determined by delay%.

See section 12 for a full description of the SOUND command.

The third and fourth examples turn all sound output on or off.

### SPC

Used within a PRINT command to print spaces.

Example:

```  PRINT "Hello";SPC(10);"Mum"
Hello          Mum
```

There are 10 spaces between the two words in the second line.

### SQR

Gives the square root of the number following it in brackets.

Example:

```  PRINT SQR(16)
4
```

### STEP

Used as part of a FOR ... NEXT structure, or to set the mouse speed.

Examples:

```  FOR n%=0 TO 10 STEP 2
FOR n=1 TO 2 STEP 0.1
FOR n%=10 TO 1 STEP -1
MOUSE STEP 4,1
```

In the first example, n% is increased by 2 each time the FOR ... NEXT loop is executed. Similarly, in the second example, n is increased by 0.1 each time (obviously an integer variable can't be used in this situation).

The third example shows how n% can be made to decrease each time round the loop. Notice that the number before TO is higher than the number after.

If STEP is not present, the variable following FOR is increased by 1 each time round the loop.

The last example sets the mouse speed to 4 (fast) for horizontal movement and 1 (slow) for vertical movement. If only one number is present, the same speed is set for both directions.

### STEREO

Sets the stereo position of a sound channel.

Example:

```  STEREO 1,127
```

The first number is the channel number and the second refers to its position. Extreme left is -127, centre is zero and extreme right is +127. The example, therefore, positions channel 1 on the right-hand side of the stereo image.

### STOP

Produces a fatal error which stops the program.

A fatal error is one with error number zero and cannot be dealt with by a program's error handler. It always stops the program, giving the error message Stopped at line.... It can be written into a program to stop it and permit scanning the state of the variables, for example:

```  IF x%>5 THEN STOP
```

following which, you can check the value of x% or any other variable.

### STR\$

Produces a string containing the number or value following it.

Example:

```  OSCLI ("Load 0.\$.MyFile "+STR\$~buf%)
```

This example shows how the value of a Basic variable may be included in a call to the operating system, usually performed by a star command. The command is an instruction to load a file into a section of memory called a buffer. The address of the first byte is the value of the variable buf%.

The STR\$ part of the command produces a string containing the characters that would appear on the screen if you told the machine to print buf%. The tilde (~) character after STR\$ means that the string contains the hexadecimal form of the number.

If the value of buf% were, say, &A680, the example would send a command to the Command Line Interpreter saying:

```  Load 0.\$.MyFile A680
```

which the CLI would understand as though it had a star on the front. The CLI normally works with hexadecimal numbers.

### STRING\$

Makes a string by repeating a shorter string.

Examples:

```  PRINT STRING\$(10,"AB")
PRINT a\$:PRINT STRING\$(LENa\$,"_")
```

The first example will display:

```  ABABABABABABABABABAB
```

The second example will print a string and underline it. After printing a\$, the program will start a new line and print underlines (_), the number being determined by LENa\$, which is the number of characters in the string (see LEN ).

### SUM

Adds together all the elements of an array.

Examples:

```  total%=SUM cost%()
```

The first example adds up the values of the elements of array cost%(). If, for example, this array had been defined with:

```  DIM cost%(9)
```

it would be able to hold 10 numbers, referred to as cost%(0) to cost%(9). The command would add all 10 numbers together.

The second example involves a string array. In this case, the strings in each element are concatenated, that is added end to end to form one long string.

### SWAP

Exchange the values of two variables or contents of two arrays.

Examples:

```  SWAP old%,new%
SWAP a%(5),b%(6)
SWAP x%(),y%()
```

In the first example, the values of old% and new% are interchanged. In the second example, the value of element 5 of array a%() is swapped with the value of element 6 of array b%().

In the final example, the entire arrays x% and y% are interchanged. If they had been DIMmed differently, each array would acquire the other's dimensions.

If two numerical values are swapped, one may be integer and the other floating point, though the floating point number, if it includes a fraction, will be rounded down to the nearest whole number. Floating point and integer arrays can't be swapped, and string arrays or variables cannot be swapped with numeric ones.

### SYS

Calls a routine in RISC OS through a Software Interrupt (SWI).

Examples:

```  SYS "OS_WriteC",65
```

The operating system has a great many system calls, that is routines which can be called through a machine code command called a software interrupt. Parameters are passed to and from these routines by means of some of the ARM processor's registers. There are 16 of these, each of which can store a 32-bit number, though only the first seven, numbered R0 to R6 are used for this purpose.

A SYS command may have the form:

```  SYS "Xxx_XxxXxx",x%,y% z% TO a%,b%,c%;f%
```

The first part, "Xxx_XxxXxx" is the name of the SWI. It is very important to get this exactly right or RISC OS will reject it. It is case sensitive.

The next part, x%,y%,z% consists of three variables, or numbers, whose values are put into registers R0, R1 and R2 before the call to the SWI. When the routine has finished, the contents of R0, R1 and R2 become the values of a%, b% and c% respectively.

If there is another variable preceded by a semicolon (;), in this case f%, its value becomes the state of the processor's flags.

The first example above calls the routine 'OS_WriteC'. This call is the machine code equivalent of VDU - the number in R0 is sent to the screen. In this case, 65 is put into R0 before the call, making this example the equivalent of `VDU 65``. Because 65 is the ASCII code for 'A', this call will print an A on the screen.

The second example calls the routine 'OS_ReadC', which is the equivalent of GET. When you call this routine it waits for you to press a key, then returns with the ASCII code for the key pressed in register R0. In this example, the number in R0 after the call becomes the value of variable char%. This example, therefore, is the equivalent of char%=GET.

For a full description of all SWIs, refer to the RISC OS Programmer's Reference Manual, published on CD-ROM by RISCOS Ltd.

### TAB

Moves the text cursor as part of a PRINT or INPUT command.

Examples:

```  PRINT TAB(3) name\$
PRINT TAB (20,10) "Do you want another go?"
```

The first example prints the string name\$ with its first character three spaces in from the edge of the screen, or the text window if it has been set. The vertical position of the cursor is not altered.

The second example prints the string in quotes 20 spaces in from the left and 10 lines down from the top of the screen or text window. It does this wherever the text cursor may have been positioned beforehand.

### TAN

Gives the tangent of the angle following it in brackets.

Example:

```  height%=width%*COS(angle)
```

### TEMPO

Gives or alters the rate of the BEAT counter, used in sound generation.

Examples:

```  rate%=TEMPO
TEMPO &800
```

The first example reads the current value of TEMPO and sets the value of variable rate% to it. The second example sets TEMPO to &800.

The value of TEMPO is in beats per centi-second, with the lowest three hexadecimal digits of TEMPO being a fraction. If TEMPO is &1000, this corresponds to one beat per centi-second, Half this number, &800, corresponds to half this speed and doubling it to &2000 corresponds to two beats per centi-second.

Loads a Basic program, which may be in the form of a text file.

Example:

```  TEXTLOAD "MyProg"
```

When a Basic program is stored in memory or saved as a file, its keywords are tokenised. This means that each keyword is represented by a token, that is, a single byte containing a number between 128 and 255. If you were to load a Basic file into memory and look at it, using the *Memory command, you would not see the keywords, but strange characters in their places. These are the tokens.

If you had a Basic program that had been saved as a text file, perhaps using TEXTSAVE, you could load it using TEXTLOAD. If the text file does not contain line numbers, it will automatically be renumbered.

### TEXTSAVE

Saves a Basic program as a text file.

Examples:

```  TEXTSAVE "MyProg"
TEXTSAVEO 3,"MyProg"
```

In a normal Basic file, each keyword is represented by a token (see TEXTLOAD). This means you can't load a Basic program into a word processor to edit it (Edit and other text editors such as Zap and StrongED are different - if you load a Basic filetype into one, it automatically de-tokenises it).

If you wish to use a Basic listing in this way, you can save it as a text file using this command.

The first example simply saves the program in the same way as SAVE (though you can't use an embedded filename). The second example, with an O on the end of the keyword, allows you to apply a LISTO option to the layout of the program (see LISTO). This example saves a text file with a space after the line number and all the structures indented.

### THEN

Used as part of IF ... THEN ... ELSE

Examples:

```  IF x%=2 THEN PROCdate
IF size%>6 THEN
```

If the expression following IF is TRUE, whatever follows THEN on the line is executed, up to ELSE, if it is present. If THEN is the last thing on the line, as in the second example, the following lines, down to ENDIF are treated as a multi-line IF ... THEN structure.

THEN is frequently optional. The first example could be written:

```  IF x%=2 PROCdate
```

There are some circumstances where THEN must be used. If it is followed by a pseudo-variable, such as TIME, you should use it. It's also needed to indicate a multi-line IF ... THEN structure.

### TIME

Reads or alters the time counter.

Examples:

```  TIME=0
t%=TIME:REPEAT UNTIL TIME-t%=200
```

TIME should not be confused with the real time and date clock, which can be accessed through variable TIME\$. It is a straight count of centi-seconds and is set to zero when the machine is switched on or reset.

The first example sets TIME to zero. The second one produces a delay of two seconds. Variable t% is set to the current value of TIME and the loop repeats until TIME exceeds this figure by 200. As it increases 100 times per second, this takes two seconds.

### TIME\$

Sets or reads the real-time clock.

Examples:

```  year\$=MID\$(TIME\$,12,4)
TIME\$="xxx, 15 Jan 1993"
```

It is possible to alter the date and time or just the date. The machine automatically works out the day of the week so it's not necessary to enter it as part of the string.

### TINT

Used with COLOUR or GCOL in 256 colour modes to set the tint, or to detect the tint of a point on the screen.

Examples:

```  COLOUR 3 TINT 255
GCOL 12 TINT 128
tint%=TINT(xpos%,ypos%)
```

TINT is an 8-bit number, but only the top two bits are used. This means that tint numbers 0 - 63 count as 0, 64 - 127 count as 64, 128 - 191 as 128 and 192-255 as 192. The first example sets the text foreground colour to bright red and the second sets the graphics foreground colour to medium green.

In the third example, tint% is set to the tint of the pixel at coordinates (xpos%,ypos%).

### TO

Part of the FOR ... NEXT structure. Also sets the mouse position.

Examples:

```  FOR count%=1 TO 10
MOUSE TO 500,400
```

The second example moves the mouse pointer to coordinates (500,400)

### TRACE

Prints the line numbers of a program as they are executed.

Examples:

```  TRACE ON
TRACE STEP ON
TRACE PROC
```

The first example turns on tracing. When the program is run, the number of each line will be displayed as it is executed. You can limit this to lines below, say, line 100 by typing:

```  TRACE 100
```

The second example stops the program after each line and waits for you to press a key. Again, you can limit this to lines below a certain number, as above.

Try running 'Boxes' from section 6 with TRACE STEP ON set.

The third example prints the name of each procedure or function as it is called. You can also use TRACE STEP PROC.

To turn off TRACE type:

```  TRACE OFF
```

### TRUE

Gives the value -1.

Example:

```  active%=TRUE
IF active% THEN PROCgame
```

If you print out the value of active%, it will be -1. In Basic, this number means TRUE. Try typing:

```  PRINT 3=3
```

The result will be -1. In the second line of the example, variable active% is tested to see if it is TRUE and PROCgame will be executed if it is.

### UNTIL

Marks the end of a REPEAT ... UNTIL loop.

Examples:

```  UNTIL n%=10
UNTIL FALSE
```

The first example might come at the end of a loop in which n% is progressively increased (though, if n% were automatically increased by the same amount each time round the loop, it would be better to use a FOR ... NEXT loop). The loop is repeated until the value of n% equals 10.

The program tests the expression which follows UNTIL and jumps back to the REPEAT command unless it is TRUE. The second example repeats indefinitely until an error occurs or Esc is pressed, as FALSE can never be TRUE.

### USR

Calls a machine code program and gives the number in register R0 on return.

Example:

```  char%=USR(code%)
```

Variable code% contains the address of the machine code to be called. On return, char% is set to the number in R0.

### VAL

Gives the numerical value of a number in the string following it in brackets.

Example:

```  PRINT VAL("45.7")+3
48.7
```

The number may consist of figures 0 - 9, a dot (.) for a decimal point and 'E' (as used in scientific notation). The number is calculated from the string up to its end or the first character other than those above.

### VDU

Sends one or more characters to the screen.

Examples:

```  VDU 7
VDU 24,300;200;1000;900;
```

A VDU code between 32 and 126 will print a character on the screen. VDU 127 is the backspace and delete character. Codes below 32 perform special functions and are frequently followed by a series of numbers to pass data. See Appendix 2 for a full list.

The first example sends a single number 7 to the screen, which produces a beep. In the second example, VDU 24 sets the size of the graphics window and is followed by eight other numbers. Because VDU codes are 8-bit numbers (0-255) and screen coordinates can go a lot higher than this, each coordinate is sent as two numbers, the low byte (number MOD 256) and the high byte (number DIV 256). To avoid having to work out these numbers, Basic allows a number to be sent as two bytes by following it with a semi-colon (;). The second example, therefore, consists of nine numbers. It is important to include the semi-colon even if a number is less than 256, and to include a semi-colon after the last number.

### VOICE

Sets a sound channel to reproduce a particular sound waveform.

Example:

```  VOICE 1,"StringLib-Hard"
```

This example sets sound channel 1 to produce the 'StringLib-Hard' waveform. As this is the channel which produces the beep, this command will alter its sound. To get back to normal, type:

```  VOICE 1,"WaveSynth-Beep"
```

or alternatively:

```  *ChannelVoice 1 1
```

The Basic command VOICE does the same job as the operating system command *ChannelVoice, except that the latter can refer to a waveform by its number and VOICE cannot.

### VOICES

Sets the number of sound channels to be used.

Example:

```  VOICES 2
```

The number of channels in use has to be a power of two - either 1, 2, 4 or 8 channels. Each channel requires a lot of processing time, so setting more channels than are needed will slow the machine down unnecessarily.

### VPOS

Gives the vertical position of the text cursor.

Example:

```  vert%=VPOS
```

If vert% is, say, 3, the text cursor is three lines down from the top of the screen or text window, if set.

### WAIT

Waits for the start of the next vertical scan of the monitor.

Example:

```  WAIT
```

This can reduce flicker when redrawing graphics.

### WHEN

Part of a CASE ... OF ... ENDCASE structure.

Example:

```  CASE num% OF
WHEN 1:PROCthis
WHEN 2,3:PROCthat
ENDCASE
```

If num% equals 1, PROCthis is executed and the program then proceeds straight to ENDCASE. If num% equals either 2 or 3, PROCthat is executed.

If num% is not 1, 2 or 3, nothing happens. To execute an instruction when the value of num% is not covered by any of the WHEN lines, see OTHERWISE.

### WHILE

Start of a WHILE ... ENDWHILE loop.

Example:

```  WHILE done%=FALSE
PROCdo_this
ENDWHILE
```

This loop is similar to a FOR ... NEXT loop except that the condition which determines whether or not the loop is executed is tested at the beginning of the loop, not the end. This allows for the situation where the loop may not be executed at all.

### WIDTH

Sets the number of characters displayed or printed on a line when listing a Basic program.

Example:

```  WIDTH=80
```

The listing will start a new line after 80 characters.

The listing on the screen will automatically go to a new line when it reaches the right-hand side of the screen. This instruction is particularly useful if you are printing out a listing and you need to limit the number of characters on each line on the paper.

© Martyn & Christine Fox 2003