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

Example:

  PRINT ABS(-5)
          5

  PRINT ABS(7)
          7

ACS

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.

See also COS.

ADVAL

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
  20   num%=ADVAL(-1)
  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

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.

See also EOR, OR.

APPEND

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

Example:

  char%=ASC("HELLO")

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

See also CHR$.

ASN

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.

See also SIN.

ATN

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.

See also TAN.

AUTO

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

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

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#

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#

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

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

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

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

Example:

  CHAIN "MyFile"

CHR$

Example:

  PRINT CHR$(65)
          A

See also ASC.

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

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

CLG

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

See also CLS.

CLOSE#

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

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

See also CLG.

COLOUR (also spelt COLOR)

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.

See also TINT.

COS

Example:

  width%=length%*COS(angle)

where angle is in radians.

See DEG and RAD for conversion between radians and degrees.

See also ACS.

COUNT

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

CRUNCH

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
    READ day%(n%)
  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

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

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.

See also RAD.

DELETE

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

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

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.

See also MOD.

DRAW

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).

See also MOVE.

EDIT

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

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

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

Example:

  PRINT END

ENDCASE

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

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

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

See also PROC.

ENDWHILE

Example:

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

EOF#

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

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.

See also AND, OR.

ERL

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

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

(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.

See also LOCAL.

EVAL

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.

See also VAL.

EXP

Example:

  a=EXP(x)

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

EXT#

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

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

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

See also CIRCLE, ELLIPSE.

FN

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

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

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:

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

See also PLOT.

GET

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.

See also INKEY, INKEY$.

GET$

GET$#

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

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

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

Examples:

  PRINT HIMEM
  HIMEM=&A0000

IF

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

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$

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

INPUT

Examples:

  INPUT length%
  INPUT name$
  INPUT "What is your name",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.

See also TAB.

INPUT#

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.

See also PRINT#.

INSTALL

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

See also LIBRARY, OVERLAY.

INSTR

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

Example:

  PRINT INT(4.5)
          4

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

LEFT$

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$.

See also MID$, RIGHT$.

LEN

Example:

  a$="ABCDE"
  PRINT LENa$
          5

LET

Example:

  LET x%=a%+b%

This has exactly the same meaning as:

  x%=a%+b%

LIBRARY

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.

See also OVERLAY.

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

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

Example:

  LISTO 3

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

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

Example:

  PRINT LN(size)

See also LOG.

LOAD

Example:

  LOAD "0.$.MyProg"

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

See also CHAIN, RUN.

LOCAL

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

Example:

  PRINT LOG(size)

See also LN.

LOMEM

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

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$

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.

See also LEFT$, RIGHT$.

MOD

Example:

  PRINT 17 MOD 7
          3

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

See also DIV.

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

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:

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

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

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

Examples:

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

  FOR n%=0 TO 4
    FOR i%=0 TO 3
      READ slot%(n%,i%)
  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.

See also STEP.

NOT

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

See CASE.

OFF

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

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

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

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.

See also CLOSE#.

OPENOUT

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.

See also CLOSE#.

OPENUP

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.

See also CLOSE#.

OR

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.

See also AND, OR.

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

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

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

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

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

Example:

  PRINT PI
  3.141592653

PLOT

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

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

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.

See also VPOS.

PRINT

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.

See also TAB.

PRINT#

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

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.

See also ENDPROC.

PTR#

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

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.

RAD

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.

See also DEG.

READ

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

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

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

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

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

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

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

(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$

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$.

See also LEFT$, MID$.

RND

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

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

See also CHAIN, LOAD.

SAVE

Examples:

  SAVE
  SAVE "MyProg"
  SAVE "ADFS::HardDisc4.$.Progs.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

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

Example:

  height%=length%*SIN(angle)

where angle is in radians.

See DEG and RAD for conversion between radians and degrees.

See also ASN.

SOUND

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

Example:

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

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

SQR

Example:

  PRINT SQR(16)
          4

STEP

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.

See also TRACE.

STEREO

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

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$

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$

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

Examples:

  total%=SUM cost%()
  PRINT SUM address$()

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

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

Examples:

  SYS "OS_WriteC",65
  SYS "OS_ReadC" TO char%

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

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

Example:

  height%=width%*COS(angle)

where angle is in radians.

See DEG and RAD for conversion between radians and degrees.

See also ATN.

TEMPO

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.

TEXTLOAD

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

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

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

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$

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

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

Examples:

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

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

TRACE

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

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

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

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

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.

See also EVAL.

VDU

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

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

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

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.

See also POS.

WAIT

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

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

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.