�TM0
�HM0
�FM0
�BM0
�PB0
�.........*......................................................................<

Help File for Advanced BASIC.  (C)1987  Colin C Dean.  Last update: 26-11-87

This document refers to the version of "Advanced BASIC" for the BBC models
B, B+ and Master 128 microcomputer with 6502 or 65C102 co-processor.

Keywords not listed below, but which are supported by BASIC-IV, are used in
the same way in Advanced BASIC.  BASIC-V keywords that are not listed below
are not recognised by Advanced BASIC.

C792
HELP
----
The help command may be used in 3 different ways:

	HELP

Used alone, HELP displays a list of BASIC status information.

	HELP <keywords>

If the keywords are recognised, a description of their use is given.

	HELP .

Gives information about all keywords.

Note that in the last 2 cases, the BASIC help file "BASHELP" needs to be
present in the current filing system's library.

For more detailed information than HELP can provide, refer to the
User Guide to Advanced BASIC.

C78E
APPEND
------
Command to append a file to a BASIC program

Syntax:

	APPEND <file name>

The file, which must contain a tokenised BASIC program, is added to the
end of the current program.  If the file contains line numbers which clash
with those in the current program, then the added part is renumbered.

D5
BPUT
----
Statement to write byte(s) to a file

Syntax:

	BPUT#<channel>,<numeric expression>
	BPUT#<channel>,<string expression> [;]

The expression is output to the file.  In the case of a string expression,
the characters are output in order, and if the expression is not followed by
a ";" then a line feed is output too.   Numeric expressions are truncated
to a single byte.

Examples:

	BPUT#file%,"Have a nice day"
	BPUT#channel,reason%
	BPUT#C%,text$+CHR$13;

BY
BY
--
The keyword BY is used to make DRAW, MOVE and POINT use relative instead of
absolute coordinates.   DRAW BY, MOVE BY and POINT BY are equivalent to
PLOT 1, PLOT 0 and PLOT 65 respectively.

Example:

	DRAW BY 100,200

If the current position is x,y then this draws from x,y to x+100,y+200.

D6
CALL
----
Statement to call a machine code subroutine.

Syntax:

	CALL <address> [,<variable> [,<variable> ...]]

This statement calls a 6502 or 65C02 routine from BASIC, passing the least
significant bytes of A%, X% and Y% to the A, X and Y registers, and the bottom
bit of C% to the carry flag.   For details of how variables are passed, refer
to the micro's User Guide.

The address to be called should be in the range 0 to &FFFF to execute code in
the 2nd processor, otherwise an I/O processor routine will be called instead.
If the address is of the form &FFrryyxx, then address &yyxx will be called in
the I/O processor (rr=FF), shadow RAM (rr=FE), or sideways ROM (rr=00-0F).
Note that when calling routines in I/O, shadow or sideways ROM memory the CALL
parameter block is not copied across the Tube.

To return register values from a machine code routine, use the USR function,
which can also access I/O and sideways ROM/RAM addresses.

Note:

Because of the use of 32-bit addresses, beware using statements like

	CALL !(wrchv)

This should be changed to

	CALL &FFFF AND !(wrchv)

C88E
CASE
----
Statement starting a CASE...OF...WHEN...OTHERWISE...ENDCASE block

Syntax:

	CASE <expression> OF

Arguments:

<expression> can be any string or numeric expression.  OF must be the last
item on the line.

Example:

	CASE X% OF
	  WHEN 0 : PRINT "zero"
	  WHEN 1,2
	  PRINT "1 or 2"
	  OTHERWISE PRINT "< 0 or > 2"
	ENDCASE

See WHEN and OTHERWISE for more details.

C88F
CIRCLE
------
Statement to draw a circle:

Syntax:

	CIRCLE [FILL] <x-centre>,<y-centre>,<radius>

The values given should be numeric expressions in the range of the graphics
coordinates, giving the centre and radius of the circle.   If FILL is used
a solid circle is drawn, otherwise an outline only.

Note:

On a model B or B+, this statement will draw nothing unless Acorn's Graphics
Extension ROM (GXR) is fitted and active.

FB
COLOUR
------
Statement to set the text colours

Syntax:

	COLOUR <numeric> [TINT <numeric>]
	COLOUR <numeric>,<numeric>

In the first case, the first numeric expression sets the foreground (0-127)
or background (128-255) text colour.   The optional TINT is ignored (allowed
for Archimedes compatibility).   In the second case, the 2nd number gives the
actual colour to be used for the logical colour given by the 1st number.   This
is equivalent to using VDU 19,<numeric>,<numeric>,0,0,0.   On the Archimedes,
it is possible to use

	COLOUR <logical>,<red>,<green>,<blue>

to precisely define a logical colour.  Advanced BASIC accepts such statements but
takes no action on them, as the necessary hardware is absent.

DE
DIM
---
(1) Statement declaring an array or claiming a block of memory
(2) Function returning dimensions of an array

As a statement, DIM is used exactly as in previous versions of BASIC.

As a function, syntax:

	DIM( <array name>() [,<numeric>] )

If no numeric is given, the result is an integer giving the number of
dimensions in the array.   With a numeric, the size of the corresponding
dimension of the array is returned.

Example:

	DIM a$(2,1,7)
	D% = DIM(a$())
	FOR I% = 1 TO D%	
	  PRINT DIM(a$(),I%)
	NEXT

This prints:

	2
	1
	7

DF
DRAW
----
Statement to draw a line

Syntax:

	DRAW [BY] <x-numeric>,<y-numeric>

Draws a line in the current graphics foreground colour, starting at the
current graphics position.   If BY is used, then the coordinates given
specify the relative displacement of the final point (as using PLOT 1),
otherwise they are taken as absolute values (as using PLOT 5).

C791
EDIT
----
Command calling ACORN's System Editor

Syntax:

	EDIT [<first line>,<last line>] [IF <text>]

Arguments:

These are the same as for LIST, allowing either all or part of the program
to be edited.

Purpose:

Enters Acorn's System Editor, to allow all or part of the current BASIC
program to be full-screen edited.   The text can be transferred back to
Advanced BASIC by use of <shift-f4> <ABASIC> in the editor.
The System Editor is present in ROM on the Master micro; on a B/B+ it may be
called from disc.   Details of how to use the editor are given in Part 2
of the Reference Manual for the Master.

Advanced BASIC calls the editor by issuing either a *EDIT or *HIEDIT command.
Which of these is used depends on its configuration status: for more details,
use "HELP CONFIGURE".

EDITO
-----
Command specifying EDIT option

Syntax:

	EDITO <numeric>

Purpose:

The current BASIC program can be transferred to the System Editor using the
EDIT command, with or without line numbers, and with or without indenting.
These options depend on which bits are set in the current EDITO value:

	bit 0 - inserts space after line number
	bit 1 - indents structures
	bit 3 - removes line numbers

Other bits should be set to zero.   Note that the bits 0,1 and 3 are used in
the same way as the corresponding LISTO bits.

Example:

	EDITO 10
	EDIT 100,400

This would transfer lines 100 to 400 of the current program to the editor,
with FOR...NEXT, WHILE...ENDWHILE, etc loops indented, and all line numbers
removed.   Note that it is not possible to remove line numbers from programs
that contains GOTO's etc:  a "Line number reference" error will occur.

On returning to Advanced BASIC from EDIT, (using <shift-f4> <ABASIC>), the
previous value of EDITO is remembered.   If it is non-zero, then leading
spaces are automatically stripped.  If bit 3 is set then line numbers are
automatically added.   The EDITO value is also copied to LISTO.   Note that
EDITO is set to zero by BREAK.

C89D
ELLIPSE
-------
Statement which draws an ellipse

Syntax:

	ELLIPSE [FILL] <x-centre>,<y-centre>,<maj>,<min> [,<angle>]

<x-centre> and <y-centre> are the coordinates of the centre of the ellipse.
<maj> and <min> are the lengths of the semi-major and semi-minor axes.
If FILL is used, a solid ellipse is drawn, otherwise an outline only.
Specifying an angle gives the number of radians between the semi-major axis
and the horizontal: this defaults to zero.

Examples:

	ELLIPSE FILL 500,500,400,100,PI/4 : REM at 45 degrees
	ELLIPSE 400,600,200,200 : REM same as CIRCLE 400,600,200

Note:

On a model B/B+ this has no effect unless Acorn's GXR ROM is present.

8B
ELSE
----
Part of the ON...GOTO/GOSUB/PROC...ELSE or IF...ELSE structures

Both ON... and the single-line IF... are identical to those in previous
versions of BASIC.  There is also a multi-line IF statement: see "HELP IF".

E0
END
---
(1) Statement ending a program
(2) Function returning top of memory used by variables

(1) Syntax:

	END

Terminates a program, without causing an error.

(2) Syntax:

	END

Variables are stored in memory starting at LOMEM and working upwards. END is
the address of the first byte after the variables block.

Example:

	PRINT HIMEM - END : REM this is number of bytes free

CB
ENDCASE
-------
This statement marks the end of a CASE...OF...WHEN...OTHERWISE...ENDCASE block.
It must be used as the first non-space item on a line.   When a WHEN clause or
an OTHERWISE clause has been executed, execution jumps to the statement after
the corresponding ENDCASE.  If a CASE block has no OTHERWISE statement, and
no WHEN match has been found, then ENDCASE signifies the end of the block.
For an example, use "HELP CASE".

CD
ENDIF
-----
This statement marks the end of an multi-line IF...THEN...ELSE...ENDIF block.
It must be the first statement on a line.  For more details, see "HELP IF".

CE
ENDWHILE
--------
The ENDWHILE statement terminates a WHILE...ENDWHILE loop:  see "HELP WHILE".

85
ERROR
-----
This has 3 uses:

(1) Part of the ON ERROR... statement
(2) Part of LOCAL ERROR or RESTORE ERROR
(3) Statement to generate a deliberate error

(1) Syntax:

	ON ERROR [LOCAL] <statements>
	ON ERROR OFF

The first case causes the specified <statements> to be jumped to after any
subsequent error.  If LOCAL is used, then when an error occurs the program
reverts to the level of procedure and function nesting, FOR...NEXT loops etc,
that was in force when ON ERROR LOCAL was used.  If LOCAL is not used, all
structures are ditched when an error occurs.

The second case restores BASIC's default error handler.

Example:

	FOR I% = -5 TO +5
	  ON ERROR LOCAL PRINT "infinity" : NEXT
	  PRINT 1/I%
	NEXT

(2) Syntax:

	LOCAL ERROR
	RESTORE ERROR

The first saves the current error handler on BASIC's stack.  If this is used
in a procedure or function, it must be after any LOCAL <variable> statements.
It may also be used outside of procedures and functions.  The second restores
the previously LOCALed error handler.   By use of these two statements, it is
possible to change from one error handler to another, and easily return to the
original.   Note that if LOCAL ERROR is used in a procedure or function, then
ending the procedure or function does an automatic RESTORE.  For an example,
type "HELP RESTORE".

(3) Syntax:

	ERROR <numeric>,<string expression>

This forces an error with ERR=<numeric> and REPORT$=<string expression>.
Note that if <numeric> is greater than 255 only the lowest byte is used,
whereas on the Archimedes 4-byte ERR values are possible.

C890
FILL
----
This has 2 uses:

(1) Statement flood-filling an area
(2) Part of CIRCLE FILL, ELLIPSE FILL or RECTANGLE FILL

(1) Syntax:

	FILL <x-coord>,<y-coord>

Flood-fills in the current graphics foreground colour, starting from the
coordinates given, in all directions until reaching a non-background colour.

(2)  Use "HELP CIRCLE" etc for details.

E6
GCOL
----
Statement to set graphics colours

Syntax:

	GCOL [<numeric>,] <numeric> [TINT <numeric>]

The same as the GCOL <numeric>,<numeric> statement of previous versions of
BASIC except that (i) the first number may be omitted (defaults to zero) and
(ii) an optional TINT may be specified (ignored, but allowed - this is used
in 256 colour MODEs on the Archimedes).

A5
GET
---
Function returning the next input character code

Example:

	REPEAT UNTIL GET = ASC("Q") : REM wait until "Q" is pressed

For information on GET$, type "HELP GET$".

BE
GET$
----
This has 2 uses:

(1) Function returning next input character
(2) Function returning a string from a file

(1) Example:

	char$ = GET$ : REM same as doing char$ = CHR$(GET)

(2) Syntax:

	GET$#<channel>

Example:

	WHILE NOT EOF#ch%
	  PRINT GET$#ch%
	ENDWHILE

Note:

A string of characters is returned from a file that has been opened
using OPENIN or OPENUP, terminated after 255 characters or at the next
null (CHR$0), linefeed (CHR$10), or carriage return (CHR$13), or on
encountering end of file.

E7
IF
--
Statement to conditionally execute further statements

Syntax:

(1)    IF <expression> [THEN] [<statements>] [ELSE <statements>]
(2)	IF <expression> THEN
	  <statements>
	  ELSE
         <statements>
	ENDIF

The <expression> must return a logical value.  If it is TRUE the THEN
statements are executed.  If it is FALSE then the ELSE statements are
executed instead.  The multi-line version (2) is identified by the fact
that THEN is the last item on the line.   The following ELSE (optional)
and ENDIF (compulsory) must each be at the start of a line.   Statements
after the ENDIF are executed regardless of whether <expression> is TRUE.

Multi-line IF statements may be nested, and their statements may also
include single-line IF's.

C89A
INSTALL
-------
Command to install a function/procedure library.

Syntax:

	INSTALL <string expression>

Arguments:

<string expression> is the name of a file containing a tokenised BASIC
program.

Purpose:

Assuming there is memory available, the file is loaded below HIMEM, which is
pulled down accordingly.  Subsequently, any call to a procedure or function
which is not found in the current program will search in the INSTALLed file.
If more than one file has been installed (Advanced BASIC allows up to 10)
they are searched last-loaded-first.  If any LIBRARY files have been loaded,
these will be scanned first.   See also "HELP LIBRARY".

INSTALLed files stay active unless BREAK is pressed or the language is
re-entered.   Because HIMEM is moved down to INSTALL a file, this can only
be done if the BASIC stack is empty: thus INSTALL cannot be used inside
procedures, etc.

LEFT$
LEFT$
-----
This has 2 uses:

(1) Function returning left part of a string
(2) Statement modifying left part of a string

(1) Syntax:

	LEFT$( <string expression> [,<numeric>] )

Returns a string containing <numeric> characters (0-255), starting at the
left end of <string expression>, (or the whole expression if its LEN is less
than <numeric> ).  IF <numeric> is not given, it defaults to LEN-1 (or 0).

(2) Syntax:

	LEFT$( <string variable> [,<numeric>] ) = <string expression>

Replaces the left-most <numeric> characters of the variable (which must
already exist) by the corresponding characters from the start of the given
expression.   If <numeric> is not given, the whole expression is used.
Note though, that in both cases the variable's length is never increased:
any extra characters in <string expression> are ignored

Examples:

	PRINT LEFT$("Cats") : REM prints "Cat"
	LEFT$(a$,2)="123" : REM changes left 2 chars of a$ to "12"

C89B
LIBRARY
-------
Command to load a function/procedure library

Syntax:

	LIBRARY <string expression>

Arguments:

<string expression> is the name of a file containing a tokenised BASIC
program.

Purpose:

Provided there is room, the file is loaded at the END of the current variables
and END is pushed up accordingly.   Any subsequent call to an unknown function
or procedure will search through all LIBRARY blocks (last-loaded-first) and
then any INSTALLed blocks (see "HELP INSTALL").   Note that LIBRARY files are
CLEARed whenever BASIC variables are CLEARed (including when modifying or
loading a new main program).  Up to 10 LIBRARY files may be loaded at any one
time (assuming there is room).

It is not possible to load LIBRARY or INSTALL files from TAPE or ROM filing
systems.  Line numbers in such files are irrelevant (but must be present!),
as any GOTOs, etc always refer to lines in the main program.   Once loaded,
such files cannot be LISTed, and should have been debugged previously.

The LVAR command can be used to list the first line of all INSTALLed and
LIBRARY blocks: Acorn recommend that each should have on its first line a REM
statement giving (i) its name, (ii) the name of a procedure contained in it
which can be called to give help info.

86
LINE
----
Statement to draw a line between 2 points

Syntax:

	LINE <x-start>,<y-start>,<x-end>,<y-end>

Equivalent to MOVE <x-start>,<y-start> : DRAW <x-end>,<y-end>

Example:

	LINE 0,0,640,512 : REM line from bottom left to middle of screen

LINE INPUT
----------
This statement is identical to INPUT LINE.

C793
LIST
----
Command to list all or part of a program

Syntax:

	LIST [<1st line> [,<last line>]] [IF <string>]

Example:

	LIST 200,300 IF RECTANGLE

This would list all program lines from line 200 to line 300 that contained
the keyword RECTANGLE.

LISTO
-----
Command to set LIST options

Syntax:

	LISTO <number>

Various bits of the number given affect the format of subsequent LISTs.
Each bit when set has the following effect:

	0    print space after line number
	1    indent all structures
	2    (not used)
	3    do not show line numbers
	4... (not used)

Example:

	LISTO 10

This would give listings with structures (FOR...NEXT etc) indented, and with
line numbers omitted.   Note that an error occurs if bit 3 is set and a GOTO
or other line reference is found.

When a program is input, any non-zero LISTO value will cause leading spaces
to be stripped.

EA
LOCAL
-----
This has 2 uses:

(1) Statement to make a variable local inside a function or procedure
(2) Statement to make error handler local

(1) Syntax:

	LOCAL <variable> [,<variable>...]

This is used in the same way as in previous versions of BASIC.

(2) Syntax:

	LOCAL ERROR

Use "HELP ERROR" for information about local error handling.

C795
LVAR
----
Command to list variable values, function/procedure names and libraries

Syntax:

	LVAR

This lists the following:

(1)  All current variables and their values (or dimensions, for arrays),
(2)  The names of all functions and procedures that have been called,
(3)  The first lines of any INSTALLed/LIBRARY programs.

Note:

CLEAR, or LOADing a new program, will remove all of the above except resident
variables (@% and A% to Z%) and INSTALLed programs.

MID$
MID$
----
This has 2 uses:

(1) Function returning part of a string
(2) Statement to modify part of a string

(1) Syntax:

	MID$( <string expression>,<numeric> [,<numeric>] )

This is used in the same way as in previous versions of BASIC

Example:

	line$ = "Have a nice day"
	nice$ = MID$(line$,8,4) : REM sets nice$ = "nice"

(2) Syntax:

	MID$( <string variable>,<n1> [,<n2>] ) = <string expression>

This overwrites characters in an existing string variable by the first <n2>
characters of the string expression (uses all if n2 not given), starting at
character position <n1> in the string variable.   Note that the length of the
variable is never changed, so surplus characters in <string expression> will
be ignored.

Example:

	line$ = "Have a nice day"
	MID$(line$,8,4) = "nasty" : REM now line$ = "Have a nast day"

EB
MODE
----
This has 2 uses:

(1) Statement to change screen mode
(2) Function returning number of current screen mode

Examples:

	MODE 3  : REM enter screen mode 3
	M%=MODE : REM sets M% equal to current mode

C897
MOUSE
-----
General purpose mouse statement, having several uses:

(1) MOUSE RECTANGLE <x-min>,<y-min>,<x-length>,<y-length>

Defines a rectangle in graphics units relative to the current ORIGIN, outside
which the mouse cannot go

Example:

	MOUSE RECTANGLE 100,100,300,300

(2) MOUSE STEP <x-step> [,<y-step>]

Sets the mouse sensitivity: the larger the step values, the more graphics
units the mouse moves through for a given physical movement.  STEP values
should be in the range -127 to +127, and if no y-step is given it is taken to
be the same as the x-step.   Default step is 1.

(3) MOUSE TO <x-coord>,<y-coord>

Sets the graphics coordinates of the mouse to the values given.

Example:

	MOUSE TO 640,512 : REM moves mouse to middle of screen

(4) MOUSE COLOUR <logical number>,<red>,<green>,<blue>

Defines the colour of the on-screen pointer, if supported.

(5) MOUSE ON [<number>]

Causes the on-screen pointer to appear at the current mouse position and to
follow its subsequent movements.  The number is the pointer shape to use,
default value 1.

(6) MOUSE OFF

Unlinks the pointer from the mouse

(7) MOUSE <variable>,<variable>,<variable>

Sets the variables (which must be integer or real) to the mouse x and y
coordinates and button status.   The button status is a 3-bit value which
indicates which buttons are currently pressed: bits 0,1,2 set for right,
middle, left respectively.

Example:

	MOUSE x,y,buttons

General notes:

In order to use a mouse from Advanced BASIC you must have a suitable mouse
driver ROM present (e.g. AMX "SuperRom" or Nidd Valley "Chauffeur"), and
must INSTALL a driver program  (e.g. "amxmice" or "nidmice", which are on
the Advanced BASIC System Disc, and support some of the above options).

EC
MOVE
----
Statement to move to a given graphics position

Syntax:

	MOVE [BY] <x-numeric>,<y-numeric>

Purpose:

Moves to the coordinates given.  If BY is used, they are taken as relative to
the current position.

Example:

	MOVE BY 100,0 : REM move 100 units to the right

CA
OF
--
Part of the CASE...OF...WHEN...OTHERWISE statement.   For more details, use
"HELP CASE".

87
OFF
---
This has several uses:

(1) Part of TRACE OFF, MOUSE OFF, or ON ERROR OFF  (use "HELP TRACE" etc)
(2) Statement to turn off the cursor

Example:

	OFF

This stops the cursor from appearing on the screen - and can be reversed by
using "ON".

EE
ON
--
This has several uses:

(1) Part of ON...GOTO, ON...GOSUB, ON ERROR, SOUND ON, MOUSE ON or TRACE ON
(2) Statement to turn on the cursor

Example:

	ON

This reverses the effect of "OFF", and is equivalent to VDU 23,1,1;0;0;0;

C891
ORIGIN
------
Statement to move the graphics origin

Syntax:

	ORIGIN <x-value>,<y-value>

Example:

	ORIGIN 640,512 : REM make centre of screen graphics origin

In this example, MOVE 0,0 would then move to the screen centre rather than
bottom left, and all subsequent graphics statements (including MOUSE) will be
affected similarly.

7F
OTHERWISE
---------
Part of the CASE...OF...WHEN...OTHERWISE statement

OTHERWISE must be the first statement on a line.  Any statement following
the OTHERWISE (on the same line or below) are executed if all previous
WHEN statements in the current CASE block have failed to match.

Use of an OTHERWISE clause in a CASE statement is optional.

Example:

	OTHERWISE PRINT "Not a valid option" : END

Use "HELP CASE" for a complete example.

C892
POINT
-----
This has 3 uses:

(1) Function returning the logical colour of a point on the graphics screen
(2) Statement to plot a point on the screen
(3) Statement to move the on-screen pointer

(1) Example:

	col% = POINT(200,300) : REM get colour at 200,300 to col%

(2) Examples:

	POINT 500,500 : REM plot a point at 500,500
	POINT BY 0,20 : REM plot a point 20 units above current position

(3) Example:

	POINT TO 640,512 : REM move on-screen pointer to centre of screen

Notes:

The token value used for (1) is &B0, but for (2) and (3) it is &C8 + &92.
To use case (3) you must have a suitable mouse/pointer driver installed.

C898
QUIT
----
The QUIT statement leaves the BASIC interpreter and returns control to the
Operating System.   In Advanced BASIC it is equivalent to "*GO F800", and
the language can be re-started by BREAK or "GO".

C893
RECTANGLE
---------
Statement to draw or move a rectangle, or to confine the mouse

(1) Syntax:

	RECTANGLE [FILL] <x-start>,<y-start>,<x-length>,<y-length>

This draws a filled rectangle or outline in the current graphics foreground
colour.

(2) Syntax:

	RECTANGLE [FILL] <x1>,<y1>,<x-length>,<y-length> TO <x2>,<y2>

This copies the rectangular region of the screen starting at x1,y1 with sides
x-length,y-length to a new position starting at x2,y2.  If FILL is used then
the original rectangle is FILLed with the current graphics background colour.

(3) Use "HELP MOUSE" for details.

Note:

On a model B or B+, (1) and (2) will do nothing unless Acorn's GXR is present.

F6
REPORT
------
The REPORT statement prints the most recent error message, e.g.

	ON ERROR REPORT : PRINT " - Error !" : END

The function REPORT$ returns a string containing the text of the most
recent error, e.g.

	IF REPORT$ = "Escape" THEN QUIT

F7
RESTORE
-------
Statement to set the data pointer, or to restore an error handler

(1) Syntax:

	RESTORE [<line number>]

This moves the DATA pointer in the same way as in earlier versions of BASIC.

(2) Syntax:

	RESTORE ERROR

This retrieves a LOCALed error handler, assuming LOCAL ERROR has been
used previously (otherwise a fatal error occurs).  If inside a procedure or
function, it is only possible to RESTORE handlers that have been made LOCAL
inside that procedure or function.  Note that at the end of a procedure or
function, any LOCAL error handler is automatically RESTOREd.

Example:

	100 LOCAL ERROR : REM save old error handler
	110 ON ERROR PRINT '"File error":GOTO 130
	120 CLOSE# channel
	130 RESTORE ERROR : REM reinstate previous error handler

Warning:

If LOCAL ERROR is used inside a GOSUB...RETURN loop in Advanced BASIC,
then RESTORE ERROR should be used before RETURN.  In Archimedes BASIC,
the RESTORE is performed automatically if missing.

F8
RETURN
------
(1) Statement to return control from a GOSUB routine
(2) Keyword to return variables from a procedure or function

(1) Used in the same way as in earlier versions of BASIC

(2) Syntax:

	DEF FN<name>   ([.... ,] RETURN <parameter> [, ....])
	DEF PROC<name> ([.... ,] RETURN <parameter>,[, ....])

Example:

	DEF PROCorder(RETURN x, RETURN y)
	IF x < y THEN SWAP x,y
	ENDPROC

If this were called by

	A% = 3 : B% = 9 : PROCorder(A%,B%)

then on exit the values 9,3 would be returned to A%,B% respectively.
By contrast, if RETURN had not been used, the values of A%,B% would always
be unchanged.

Restrictions:

The procedure or function must be called with the name of an existing variable
and not an expression if a RETURN is specified: e.g. in the above case calling
PROCorder(3,B%+7) would generate an error.   In Advanced BASIC, no more than
10 parameters may be returned from a procedure or function.

RIGHT$
RIGHT$
------
This has 2 uses:

(1) Function returning right part of a string
(2) Statement modifying right part of a string

(1) Syntax:

	RIGHT$( <string expression> [,<numeric>] )

Returns a string containing <numeric> characters (0-255) from the right end
of <string expression>, (or the whole expression, if length < numeric).
If a number is not given, only the right-most character is returned.

(2) Syntax:

	RIGHT$( <string variable> [,<numeric>] ) = <string expression>

Replaces the right-most <numeric> chcracters of an existing variable by the
corresponding characters from the start of the given expression.  The whole
expression is used if <numeric> is not specified, but in all cases the length
of the variable is never increased - any extra characters in the expression
are ignored.

Examples:

	r$ = RIGHT$("Fish") : REM sets r$ = "h"
	RIGHT$(text$) = "." : REM last character of text$ changed to "."

C799
SAVE
----
Command to save current program to a file

Syntax:

	SAVE [<file name>]

It is possible to save a program without specifying a name, but only if
the first line of the program gives its name in the form

	REM > <name>

e.g.

	10 REM > prog1

D4
SOUND
-----
Statement to generate a sound, or to turn sound output off or on

Syntax:

(1) SOUND <expression>,<expression>,<expression>,<expression>
(2) SOUND OFF
(3) SOUND ON

(1) generates a sound in the same way as in previous versions of BASIC.
Note that in Archimedes BASIC sound is handled differently, and it is
possible to pass 5 parameters to SOUND.  Advanced BASIC does not allow this.

(2) Disables sound output.  Equivalent to *fx210,1

(3) Re-enables sound output.  Equivalent to *fx210,0

C68E
SUM
---
This is an Archimedes BASIC keyword, returning the sum or concatenation of
the members of an array.  Advanced BASIC does not support this (although it
does tokenise the keyword correctly) and gives a "Missing code" error if you
try to use it.   Other whole-array operations of Archimedes BASIC are also
not supported, with the exception of the DIM function (see "HELP DIM").

C894
SWAP
----
Statement to swap the contents of 2 numeric or string variables

Examples:

	SWAP x,y
	SWAP real,integer%
	SWAP first$,second$
	SWAP string$, $S%

C899
SYS
---
Statement to call operating system routines

Syntax:

	SYS <exp1> [,<exp2>....] [TO <var1> [,<var2>....] [;<varf>]

This is the preferred way of calling the operating system in Archimedes BASIC,
as it is faster and more versatile than CALL &FFxx, etc.  In Advanced BASIC,
most common SYS calls are supported, but some are slower than using CALL or
USR (i.e. all except those that access files or wait for keyboard input).
For a complete description and a list of which calls are supported, refer to
the User Guide.   Full details of all SYS calls on the Archimedes can be
found in its Programmers' Reference Manual.

Examples:

	SYS 0,66                                           : REM VDU 66
	SYS "OS_CLI","help"                                : REM does *help
	SYS "OS_File",5,name$ TO exists,,load,exec,length  : REM get file info

8C
THEN
----
Part of IF...THEN...ELSE or IF...THEN...ELSE...ENDIF

Use "HELP IF" for details.

91
TIME
----
Reads or writes the operating system centi-second clock.

Used in the same way as in earlier versions of BASIC.

TIME$
-----
Reads or writes the real-time clock

Examples:

	PRINT TIME$
	TIME$ = "Tue, 1 Sep 1987"
	TIME$ = "15:30:27"
	TIME$ = "FRI,20 APR 1962.03:20:00"

Notes:

On a Master 128 micro the operating system provides support to enable TIME$
to be used.  On a model B or B+ it can only be used if suitable hardware or
software emulation (e.g. Tubelink's Utility RAM) has been added.

C89C
TINT
----
Used on an Archimedes to affect the colours displayed in 256-colour modes,
as part of the COLOUR or GCOL statements.  In Advanced BASIC this keyword is
accepted but ignored, as there is no hardware support.

FC
TRACE
-----
Statement to allow tracing of program execution

Syntax:

(1) TRACE [STEP] ON
(2) TRACE [STEP] <line number>
(3) TRACE [STEP] PROC
(4) TRACE OFF

(1) causes all line numbers to be printed when they are executed,
(2) is the same, except only lines less than that given are displayed,
(3) causes procedure and function names to be displayed when called,
(4) switches off tracing.

In cases (1) to (3), single stepping (where the program waits for a key to
be pressed after each number or name is shown) occurs if STEP is used.

C896
WAIT
----
Wait for vertical sync

This has the same effect as *fx19 - the program waits until the next
vertical sync (these occur 50 times a second) before continuing.

From machine code this can be used to time screen-updates so that flicker
is avoided.  In BASIC on a 6502 machine this may not be very effective
because of the slower program execution speed.

C9
WHEN
----
Part of the CASE...OF...WHEN...OTHERWISE...ENDCASE statement

Use "HELP CASE" for a general example of this structure.  WHEN must be the
first statement on a line.  It is followed by one or more values to match.
Statements to execute if match is succesful may follow on the same line
after ":" or on subsequent lines.  The matched statements are terminated by
the next WHEN, OTHERWISE or ENDCASE (unless there is a nested CASE structure)
and control then jumps to the statement after the ENDCASE.

Examples:

	WHEN FALSE : PRINT "Doesn't exist"
	WHEN "Y","y" : OSCLI ("delete " + name$)

C895
WHILE
-----
Statement starting a WHILE...ENDWHILE loop

The WHILE...ENDWHILE structure enables program loops to be built which
test a condition at the start of a loop (whereas REPEAT...UNTIL tests at
the end). e.g. the following prints the numbers 0 to 9:

	X%=0 : WHILE X%<10 PRINT X% : X%=X%+1 : ENDWHILE

If the test condition is initially FALSE, then all statements until the
ENDWHILE are ignored.

WHILE and ENDWHILE may be used anywhere in a program, and in Advanced BASIC
may be nested up to a maximum depth of 10.

CONFIGURE
Advanced BASIC Configuration Values
-----------------------------------
Advanced BASIC has a 3-bit configuration value.  Setting each bit has the
following effect:

	bit 0 - "*BASIC" after subsequent BREAKs enters Advanced BASIC
	bit 1 - EDIT calls "*EDIT" (as opposed to "*HIEDIT")
	bit 2 - reserved

Bit 0 is only effective if Advanced BASIC is in a lower ROM than HIBASIC.

On a Master micro (or a B/B+ with Tubelink's Utility RAM fitted) the
current status can be read using *STATUS, and changed by *CONFIGURE

Examples:

	*STATUS ABASIC
	1

	*CONFIGURE ABASIC 3

On a model B/B+ without *STATUS and *CONFIGURE commands, use "*ABASIC ?" to
read status, and "*ABASIC <number>" to change it.

On a Master it is also possible to specify Advanced BASIC as the default
language ROM, which is entered at CTRL-BREAK. e.g. if in ROM 6, use

	*CONFIGURE LANG 6

[
The Advanced BASIC Assembler
----------------------------
The assembler recognises all the 65C02 mnemonics (including the Rockwell-
specific BBR, BBS, RMB and SMB) and has several other extensions:

OPT
---
Values of OPT outside the range 0-7 may be used, in order to assemble code
directly to the I/O processor, to sideways RAM, or to a file.  Below is a
summary of output destinations:

	 0 - 3    to P% in 2nd processor
	 4 - 7    to O% in 2nd processor
	 8 - 11   to OPENout file
	12 - 15   to OPENup file, PTR# = O%
	16 - 19   to P% in I/O processor
	20 - 23   to O% in I/O processor
	24 - 27   to P% in sideways RAM
	28 - 31   to O% in sideways RAM
	32 - 63   no code generated

OPEN and SHUT
----     ----
These pseudo-opcode are used with OPT values 8-15 for assembly to files, e.g.

	FOR opt% = 8 TO 10 STEP 2
	[OPT opt%
	 OPEN "NiceDay"                 \ opens file for output
	 EQUS "Have a nice day"+CHR$13  \ these chars go to file
	 SHUT ""                        \ no need to give name again
	]
	NEXT opt%

For OPT values 8-11, bytes are output sequentially from the start of the file.
If values from 12-15 are used, the file is opened for update instead of output,
and O% sets the file pointer (PTR#) before each byte is output.

To set the load and execution addresses of a file when it is SHUT, use

	SHUT "<fsp>" , <load address> , <exec address>

where <address> is any BASIC expression returning a number.  In this case
the filename may not be abbreviated.

ROM
---
For assembly to sideways RAM, the ROM socket number (0-15, or FF for Shadow)
should be given, e.g.

	FOR opt% = 24 TO 27 STEP 3
	P% = &8000
	[OPT opt%
	 ROM 7           \ assembling to sideways RAM number 7
	 JMP language
	 JMP service
	...etc, etc.

If you have non-standard sideways RAM, you may need to write-page it
before you can assemble into it: refer to your sideways RAM user guide
for details.

Extensions to EQU
-----------------
As well as EQUB, EQUW and EQUD, which assemble an integer value to 1 2 or 4
bytes, the assembler recognises:

	EQUR <numeric>  \ assembles 5-byte real number
	EQUF "<fsp>"    \ includes pre-assembled file

Zero-Page Locations
-------------------
The only zero-page locations that may be used by a machine-code program in the
second processor called from Advanced BASIC are &70 to &CF inclusive.

Calling Assembled Code
----------------------
Code in the I/O processor or in sideways ROM/RAM can be called directly by
using CALL or USR, e.g.

	CALL &FFFF0C00 : REM calls &C00 in I/O

For more details, use "HELP CALL".