A few years back I had the idea to jot down all of the little noteworthy things I'd found out about BBC BASIC. Pretty soon I had a flaky set of notes, written on bits of torn off paper and scribbled down hastily in notebooks.

    Some time later, whilst searching for useful things to fill up my web space with, I realised that these notes would be of value to others as well as myself and decided to turn them all into a web page, which you find here.

    These tips and tricks are intended for the more experienced BASIC coder - if you are new to programming, or unfamiliar with BBC BASIC V, then you could find that you will confuse yourself by reading these pages.

    Sometimes most of the help you need on a BASIC keyword can be found out from the HELP command, which provides some simple help on most of BASIC's keywords.

    Although this page is not intended to replace Acorn's own BASIC reference manual, there will be overlap at some point.

The DIM statement is often used incorrectly, for example consider 'DIM b% 256', for which BASIC allocates 260 bytes. The parameter passed to DIM is indexed at 0, so if you want to allocate an n byte block you should specify n-1 bytes in the DIM statement. BASIC always allocates blocks in multiples of four bytes, so non-word-aligned values will always be rounded up to a word boundary, hence in the above example, the DIM statement tells BASIC to allocate 257 bytes and BASIC rounds this up to 260.

Remember that the first element of an array or DIMmed block is at zero, not one.

Using a statement such as 'DIM b% -1' will set aside no space for b%, but will set b% to the address of the start of the next free location. This value is the last byte+1 of the last block allocated. This makes it easy to set aside space for assembly and assign the L% range-check value simultaneously. e.g. 'DIM code% 255, L% -1'. As BASIC always allocates blocks as multiples of four bytes, the block will always be word aligned.

Other negative values in DIM statements will generate an error.

Speaks for itself really. For any serious work, you're often better off just writing some simple memory management routines.

TRACE is a very useful statement. It is used as follows:

TRACE [STEP] ON|OFF|PROC|<number>

Trace [in single step mode] on or off or procedure or function calls or lines below the number.

TRACE TO <string>

Send all output to stream <string>.

TRACE CLOSE

Close stream output.

Expression: TRACE

Gives handle of the stream.

By using BPUT#TRACE,"string" then "string" will be sent to the trace file. Typically you would write IF TRACE THEN BPUT#TRACE,"string".

LIST [<line number>][,[<line number>]][IF<pattern>]. list section [if pattern]
LISTO <option number>. Bits mean:-
0: space before line
1: indent structure
2: split lines at ":"
3: don't list line number
4: list tokens in lower case

DATA statements tend to be intertwined with line numbers, which we don't really want to have to think about anymore. RESTORE [+][number] allows the data pointer to be set to the first DATA in the program - 'RESTORE' - the next set of data ahead of the statement - 'RESTORE +' - or the data number lines ahead - 'RESTORE +number'.

You can save the current data pointer by using 'LOCAL DATA' and restore it to its previous value by using 'RESTORE DATA'. RESTORE DATA is performed automatically if you use LOCAL DATA in a function or procedure.

The SUMLEN function returns the sum of the lengths of all the strings in a string array. For example:

PRINT "There are ";SUMLEN(strings$());" characters in the array."

In addition to its usual function of returning the remainder of a division, the MOD function will return the modulus (square root of the sum of the squares of each element) of a numeric array. For example:

normalisedvector() = vector() / MOD vector()

As a function, QUIT will return TRUE if BASIC was invoked with the -quit command line parameter.

CRUNCH is a simple BASIC compressor built into the interpreter itself. The reason that it is simple, is that even the 'clever' BASIC compressors can't always compress a program and retain its original meaning (i.e. errors creep into the expressions within the code).

The statement is passed a single integer (or expression) which is a bitfield, constructed as follows:

• 0 - Remove spaces before statements
• 1 - Remove spaces in statements
• 2 - Remove all but the first REM statement
• 3 - Remove empty statements
• 4 - Remove empty lines

BASIC will automatically CRUNCH programs if BASIC$Crunch is defined. I personally don't advise this as some programs object to being CRUNCHed and voice their objection by locking up the machine. :-(

The RETURN statement can be used in the declaration of procedures and functions to indicate that the variable passed is to have its value written back when the function exits. For example:

DEF PROCtimestwo(RETURN number%)
number% = number% * 2
ENDPROC

Any variable passed to this procedure would normally be protected from being changed. Once the RETURN is added, any changes to the variable is automatically reflected when the procedure or function exits.

A side effect of using this is that if you call a procedure or function which uses RETURN with an actual parameter - e.g. PROCtimestwo(55) - then BASIC will produce the error 'Invalid RETURN actual parameter'.

This expression alters the amount of memory allocated to BASIC, so you can actually change the wimpslot of your program without resorting to using SYS "Wimp_SlotSize"..., which is larger and trickier.

For example, the expression 'END = END + 4096' will set the slot of the program to be whatever it takes, plus 4K of free space.

I think of this as obvious, but I'll point it out anyway: Use Integer variables in preference to Real variables wherever possible - they're faster. Although in most cases, they use the same amount of memory - both use 12 bytes for a single-character variable name. (BASIC VI uses 16 bytes for a Real variable as its real variables are stored as actual floating-point numbers).

Using an integer as a set of flags is much more space efficient than using several variables, or variable arrays, to do the same job.

Where operator priority allows, you can often omit brackets. For example, the following code:

(a * b) << (c + d - e)

can be rewritten as the following:

a * b << c + d - e

which will still yeild the same result, as the numerical operators all have a higher priority than the shift (<<) operator.

Brackets can be omitted on most functions e.g. LEN(file$) becomes LENfile$

Using an integer as a set of flags is much more efficient than using several variables, or variable arrays, to do the same job.

Use '<value> AND NOT <bitmask>' to clear bits in Integer variables. You can also use statements such as '<value>AND-4' as -1 is equivalent to &FFFFFFFF.

<>0 can be omitted in most cases if it corresponds to a boolean state. For example, 'IF n<>0 THEN ...' can be replaced with 'IF n THEN ...'. This works as zero is interpreted to be FALSE and any non-zero is interpreted to be TRUE (its actual value is -1). All the IF statement does is check if the expression given to see if it is TRUE or FALSE.

You access memory using the ! (word at), ? (byte at) and | (real at) operators. Instead of using '?(address+n)' you can use 'address?n'. 'address?0' is equivalent to '?address'.

Using the << shift command to replace multiplications by power-of-two numbers will yeild a speedup.

Although you can write code that looks like this:

IF boolean-expression THEN variable=TRUE ELSE variable=FALSE

Use your brain! With a bit of thought you can see that an exact equivalent is:

variable=(boolean-expression)

There's usually plenty of code which can bereduced like this.

Unlike certain other languages, BASIC cannot reallocate DIMmed memory blocks (except on a CLEAR statement). This means that you have to be very careful about when and where you allocate memory. Consider the following code fragment:

DEF PROCdosomething
LOCAL mem%
DIM mem% 255
...
ENDPROC

Each time this is called, 256 bytes will be allocated. Once the procedure is exited the memory will not be returned to the control of the interpreter (even though mem% is marked as LOCAL) so if this procedure is repeatedly called, you will eventually run out of memory.

Saying that, if you DIM string and integer arrays and they're marked as local, then you will get the memory back when the routine finishes.

This is a feature of the BasCompress and StrongBS BASIC compressors that I find very useful indeed.

The compressor notes all variables that don't change over the duration of the program - constant variables - and replaces all references to them in the output file with their equivalent constant value.

Because constant values tend to be faster than constant variables, this gives a speedup as well as (often) reducing the size of the program.

LIBRARY "<file>" allows all the functions and procedures of the specified BASIC file to be used in your program.

It's usual for programmers to build up collections of their own generic routines which they amass into libraries. The LIBRARY statement allows these libraries to be loaded into BASIC's memory at run-time for use by your program.

Whole arrays (of any type) can be assigned in one go by supplying a set of parameters, rather than a single value.

For example:

transformation()=1, 0, 0, 0, 1, 0, 0, 0, 1

The parameter list does not need to have as many entries as the array that is being assigned.

You can also do block operations leading to very powerful statements such as:

coordinate() = coordinate() * transformation()

Note that the last subscript changes quickest, so, using a 3x3x3 array as an example, the following would happen:

(0, 0, 0) = first
(0, 0, 1) = second
(0, 0, 2) = third
(0, 1, 0) = fourth
(0, 1, 1) = fifth
(0, 1, 2) = sixth
(0, 2, 0) = seventh
  . . .   = n'th
(2, 2, 2) = twenty-seventh

@% sets the format of the printed numerical output and, optionally, string output. It is an unusual variable as you can assign it both a number and a string, the string being an ANSI printf format string. PRINT @% will display a number. The number is a four-byte field and constructed as:

<&80 for "," separator, &00 for "."><0,1,2 for G,E,F><digits after '.'><digits before '.'>

The default format is "G10.9".

Multiple-line THEN statements can often be compressed down to a single line to provide a useful saving of space. However, doing this can lead to some problems when the compressed structures don't behave as you would expect them to. For example, say you have a construct like this:

IF a THEN
  IF b THEN
    a-and-b
  ELSE
    a-and-not-b
  ENDIF
ENDIF

and you compress it down to:

IF a THEN IF b THEN a-and-b ELSE a-and-not-b

then BASIC will execute a-and-not-b when a or b is FALSE - the first matching ELSE found is executed - which obviously isn't equivalent to the multiple-line construct.

The TIME statement returns the number of centiseconds elasped since the machine was switched on. By default, it is equal to the value returned from OS_MonotonicTime. This value is used in some OS calls, such as Wimp_PollIdle to represent time delays.

TIME uses the OS_Word calls 1 and 2 to read and write the system clock - it is not private to each running BASIC program. This means that if you're using TIME in a multitasking program and another program issues TIME = <some value> (to change BASIC's idea of the time), then your program will be affected.

Some programs use code such as:

SYS "Wimp_PollIdle", mask%, block%, TIME+200 TO reason%

to return to their program after a specific time interval (in this example, in two seconds time). This code would not function as expected if another program issued the TIME = ... statement. In particular if TIME is reset to zero, then certain tasks might start polling continuously, absorbing a lot of desktop time.

You can avoid this mess by replacing TIME references with calls to a FNtime routine which returns the real monotonic time:

DEF FNtime
LOCAL time%
SYS "OS_ReadMonotonicTime" TO time%
= time%

BASIC allows you to omit the THEN statement on a single-line IF structure. If you want to make sure your program will be handled correctly when passed through a BASIC compressor program, you must always use the THEN statement. This is because expressions such as 'IF x<>0 E% = 1' can get compressed to 'IFx<>0E%=1'. This will confuse the interpreter, as it will think that the '0E' is a number.

Using the >> operator to shift down the topmost bit (or something which includes the topmost bit) of a word will not work, as it is a signed operator. Instead use the >>> operator which will shift down unsigned. (There is no equivalent <<< operator.)

Beware of trailing spaces after THEN statements. For example:

IF a=5 THEN <-- trailing space here
  b=7
ENDIF

This will set the value of variable b to 7 irrespective of the value of a.

If you use a LOCAL statement in a procedure or function, then don't assume that the variables you specify will be created and initialised for you, because there's no guarantee that it will. This is true even if your variables exist before the procedure or function is called - you will still need to initialise them.

It's actually possible to assign a variable from a procedure by doing something like PROCassign("greeting$", "hello"). The trick is in judicious use of the EVAL and RETURN statements.

PROCassign("greeting$", "hello")
END

DEF PROCassign(a$,b$)
unused = EVAL("FNassign2(" + a$ + "," + CHR$34 + b$ + CHR$34 + ")")
ENDPROC

DEF FNassign2(RETURN a$, b$)
a$ = b$
= 0

Obviously, this version will only work for strings, but it can be adapted for other data types.

The STRING$(<number>,<string>) statement can be used to create temporary buffers on the fly, for example when calling a SWI which needs a string buffer for output. However, their maximum length is 255 which is one less than the 256 character buffer you usually need. For example:

DEF FNmessage(msg$)
LOCAL b%, l%
SYS "MessageTrans_Lookup", msg%, msg$, STRING$(255,"*"), 256 TO ,, b%, l%
b%?l% = 13%
= $b%

Note: This can be a bit tricky at times, you really have to read whatever has been put in the buffer immediately after the call, otherwise it may get overwritten.

The natural way to code a block memory movement procedure in BASIC is to write a FOR loop with a load/store pair inside. However, this is a slow way to do it. Using a small ARM code block copier, it will go zillions of times faster^*.

Although assembly can be assembled at run-time. However, if the code is getting quite lengthy it's best to store it in a file and load it in when your program starts up.

^* Approximate figure. ;-)

Note: assembler area limit checking, exported routines from CALL.

The function INKEY(-256) returns the operating system version identifier - a unique value of which is returned for each release of the host operating system. This value is not related to the '3.11', '3.71', and so on, version numbers as it has to retain compatibility with the identifiers from other Acorn OS's.

This isn't specifically a BASIC feature, as all the interpreter really does is return the value available from calling SWI OS_Byte 129,0,&FF. The identifiers are:

Using the more recent versions of system calls is likely to provide performance increases and enhanced functionality. For example:

IF wimp%>320 THEN
  SYS "Wimp_ResizeIcon"...
ELSE
  SYS "Wimp_DeleteIcon"...
  misc%!4 = win% : misc%!16 = x% : ...
  SYS "Wimp_CreateIcon"...
ENDIF

Another example is the RISC OS 3.6 sprite plot calls which can now plot using a simple ordered dither, if you specify a bit in R0.