A function which will return -1 (TRUE) if the data file whose file handle is the argument is at, or beyond, its end. In other words, when PTR# points beyond the current end of the file. When reading a serial file, EOF# would go true when the last byte of the file had been read.

EOF# is only true if PTR# is set beyond the last byte written to the file. It will NOT be true if an attempt has been made to read from an empty block of a sparse random access file. Because of this, it is difficult to tell which records of a random access file have had data written to them. These files need to be initialised and the unused records marked as empty.

Writing to a byte beyond the current end of file updates the file length immediately, whether the record is physically written to the disk at that time or not. However, the file must be closed in order to ensure that all the data written to it is physically written to the disk.

The operation of bitwise integer logical exclusive-or between two items. The two operands are internally converted to 4 byte integers before the EOR operation. EOR will return a non-zero result if the two items are different.

You can use EOR as a logical operator or as a 'bit-by-bit' (bitwise) operator. The operands can be boolean (logical) or numeric.

Unfortunately, BBC BASIC does not have true boolean variables; it uses numeric variables and assigns the value 0 for FALSE and -1 for TRUE. This can lead to confusion at times. (See NOT for more details.)

In the example below, the operands are boolean (logical) and the result of the tests (IF) A=2 and (IF) B=3 is either TRUE or FALSE.

The result of this example will be FALSE if A=2 and B=3 or A<>2 and B<>3. In other words, the answer will only be TRUE if the results of the two tests are different.

The brackets are not necessary, they have been included to make the example easier to follow.

The last example uses EOR in a similar fashion to the numeric operators (+, -, etc).

Suppose X was -20, the EOR operation would be:

A function returning the line number of the line where the last error occurred.

If there was an error in a procedure call, the line number of the calling line would be returned, not the line number of the definition.

The number returned by ERL is the line number printed out when BBC BASIC (Z80) reports an error.

See the Error Handling sub-section for more information on error handling and correction.

A function returning the error code number of the last error which occurred (see the Annex entitled Error Messages and Codes).

Once you have assumed responsibility for error handling using the ON ERROR statement, you can use this function to discover which error occurred.

See the Error Handling sub-section for more information on error handling and correction.

A function which applies the interpreter’s expression evaluation program to the characters held in the argument string.

In effect, you pass the string to BBC BASIC (Z80)'s evaluation program and say 'work this out'.

You can use this function to accept and evaluate an expression, such as a mathematical equation, whilst the program is running. You could, for instance, use it in a 'calculator' program to accept and evaluate the calculation you wished to perform. Another use would be in a graph plotting program to accept the mathematical equation you wished to plot.

The example below is a 'bare bones' calculator program which evaluates the expression typed in by the user.

You can only use EVAL to work out functions (like SIN, COS, etc). It won’t execute statements like MODE 0, PRINT, etc.

A function returning 'e' to the power of the argument. The argument must be < 88.7228392. The 'natural' number, 'e', is approximately 2.71828183.

This function can be used as the 'anti-log' of a natural logarithm. Logarithms are 'traditionally' used for multiplication (by adding the logarithms) and division (by subtracting the logarithms). For example,

will calculate 2.5*2 by adding their natural logarithms and print the answer.

A function which returns the total length of the file whose file handle is its argument.

In the case of a sparse random-access file, the value returned is the complete file length from byte zero to the last byte written. This may well be greater than the actual amount of data on the disk, but it is the amount of disk space allocated to the file by CP/M-80.

The file must have been opened before EXT# can be used to find its length.

A function returning the value zero.

BBC BASIC (Z80) does not have true Boolean variables. Instead, numeric variables are used and their value is interpreted in a 'logical' manner.

A value of zero is interpreted as FALSE and NOT FALSE (in other words, NOT 0) is interpreted as TRUE. In practice, any value other than zero is considered TRUE.

You can use FALSE in a REPEAT----UNTIL loop to make the loop repeat for ever. Consider the following example.

Since 'terminator' will never be zero, the result of the test 'terminator=0' will always be FALSE. Thus, the following example has the same effect as the previous one.

Similarly, since FALSE=0, the following example will also have the same effect, but its meaning is less clear.

See the keyword AND for logical tests and their results.

A keyword used at the start of all user declared functions. The first character of the function name can be an underline (or a number)

If there are spaces between the function name and the opening bracket of the parameter list (if any) they must be present both in the definition and the call. It’s safer not to have spaces between the function name and the opening bracket.

A function may be defined with any number of parameters of any type, and may return (using =) a string or numeric result. It does not have to be defined before it is used.

A function definition is terminated by '=' used in the statement position.

The following examples show the '=' as part of a program line and at the start of a line. The first two examples are single line function definitions.

Functions are re-entrant and the parameters (arguments) are passed by value.

You can write single line, multi statement functions so long as you have a colon after the definition statement.

The following function sets the print control variable to the parameter passed and returns a null string. It may be used in a PRINT command to change the print control variable (@%) within a print list.

Functions have to return an answer, but the value returned by this function is a null string. Consequently, its only effect is to change the print control variable. Thus the PRINT statement

will print X in G9z10 format and Y in F2z10 format. See the keyword PRINT for print format details.

A statement initialising a FOR…​NEXT loop. The loop is executed at least once.

The FOR…​NEXT loop is a way of repeating a section of program a set number of times. For example, the two programs below perform identically, but the second is easier to understand.

You can GOTO anywhere within one FOR…​NEXT loop, but not outside it. This means you can’t exit the loop with a GOTO. You can force a premature end to the loop by setting the control variable to a value equal to or greater than the end value (assuming a positive STEP).

It is not necessary to declare the loop variable as an integer type in order to take advantage of fast integer arithmetic. If it is an integer, then fast integer arithmetic is used automatically. See Annex E for an explanation of how BBC BASIC (Z80) recognises an integer value of a real variable.

Any numeric assignable item may be used as the control variable. In particular, a byte variable (?X) may act as the control variable and only one byte of memory will be used. See the Indirection sub-section for details of the indirection operators.

Because a single stack is used, you cannot use a FOR…​NEXT loop to set array elements to LOCAL in a procedure or function.

A statement which sets the graphics foreground or background logical colour to be used in all subsequent graphics operations.

The first number sets the mode of action, which is currently ignored.

The modes are: 0 plot the colour specified 1 OR the specified colour with that already there 2 AND the specified colour with that already there 3 Exclusive-OR the specified colour with that already there 4 Invert the colour already there

A function and compatible string function that reads the next character from the keyboard buffer (it waits for the character).

See the keyword INKEY for a way of emptying the keyboard buffer before issuing a GET.

GET and GET$ wait for a 'key' (character) to be present in the keyboard buffer and then return the ASCII number of the key (see Annex A) or a string containing the character of the key. If there are any characters in the keyboard buffer when a GET is issued, then a character will be returned immediately. See the keyword INKEY for a way of emptying the keyboard buffer before issuing a GET.

GET and GET$ do not echo the pressed key to the screen. If you want to display the character for the pressed key, you must PRINT it.

You can use GET and GET$ whenever you want your program to wait for a reply before continuing. For example, you may wish to display several screens of instructions and allow the user to decide when he has read each screen.

GET can also be used to input data from an I/O port:

Returns the ASCII character at position x,y.

A statement which calls a section of a program (which is a subroutine) at a specified line number. One subroutine may call another subroutine (or itself).

The only limit placed on the depth of nesting is the room available for the stack.

You may calculate the line number. However, if you do, the program should not be RENUMBERed. A calculated value must be placed in brackets.

Very often you need to use the same group of program instructions at several different places within your program. It is tedious and wasteful to repeat this group of instructions every time you wish to use them. You can separate this group of instructions into a small sub-program. This sub-program is called a subroutine. The subroutine can be 'called' by the main program every time it is needed by using the GOSUB statement. At the end of the subroutine, the RETURN statement causes the program to return to the statement after the GOSUB statement.

Subroutines are similar to PROCedures, but they are called by line number not by name. This can make the program difficult to read because you have no idea what the subroutine does until you have followed it through. You will probably find that PROCedures offer you all the facilities of subroutines and, by choosing their names carefully, you can make your programs much more readable.

A statement which transfers program control to a line with a specified or calculated line number.

You may not GOTO a line which is outside the current FOR…​NEXT, REPEAT…​UNTIL or GOSUB loop.

If a calculated value is used, the program should not be RENUMBERed. A calculated value must be placed in brackets.

The GOTO statement makes BBC BASIC (Z80) jump to a specified line number rather than continuing with the next statement in the program.

You should use GOTO with care. Uninhibited use will make your programs almost impossible to understand (and hence, debug). If you use REPEAT----UNTIL and FOR----NEXT loops you will not need to use many GOTO statements.

A pseudo-variable which contains the address of the first byte that BBC BASIC (Z80) will not use.

HIMEM must not be changed within a subroutine, procedure, function, FOR…​NEXT, REPEAT…​UNTIL or GOSUB loop.

BBC BASIC (Z80) uses the computer’s memory to store your program and the variables that your program uses. When BBC BASIC is first loaded and run it checks to find the highest memory address it can use. If this is in excess of &10000 bytes, HIMEM is set to &10000. Otherwise, HIMEM is set to the maximum available address.

If you want to use a machine code subroutine or store some data for use by a CHAINed program, you can move HIMEM down. This protects the area above HIMEM from being overwritten by BBC BASIC (Z80). See the Assembler section and the keyword CHAIN for details.

If you want to change HIMEM, you should do so early in your program. Once it has been changed it will stay at its new value until set to another value. Thus, if you wish to load a machine code subroutine for use by several programs, you only have to change HIMEM and load the subroutine once.

USE WITH CARE.

A statement which sets up a test condition which can be used to control the subsequent flow of the program. It is part of the IF----THEN----ELSE structure.

The word THEN is optional under most circumstances.

The IF statement is the primary decision making statement. The testable condition (A=B, etc) is evaluated and the answer is either TRUE or FALSE. If the answer is TRUE, the rest of the line (up to the ELSE clause if there is one) is executed.

The '=' sign has two meanings. It can be used to assign a value to a variable or as part of a test. The example shows the two uses in one program line.

In English this reads "A becomes equal to the result of the test B=C". Thus if B does equal C, A will be set to TRUE (-1). However, if B does not equal C, A will be set to FALSE (0). The example below is similar, but A will be set to TRUE (-1) if 'age' is less than 21.

Since the IF statement evaluates the testable condition and acts on the result, you can use a previously set variable name in place of the test.

The two examples below will print 'Under 21' if the value of 'age' is less than 21.

A function and compatible string function which does a GET/GET$, waiting for a maximum of 'num' clock ticks of 10ms each. If no key is pressed in the time limit, INKEY will return -1 and INKEY$ will return a null string. The INKEY function will return the ASCII value of the key pressed.

Since INKEY and INKEY$ remove characters from the keyboard buffer, one character will be returned every time an INKEY is issued. A single INKEY will return the first character and leave the rest in the keyboard buffer.

You can use this function to wait for a specified time for a key to be pressed. A key can be pressed at any time before INKEY is used.

Pressed keys are stored in an input buffer. Since INKEY and INKEY$ get a character from the normal input stream, you may need to empty the input buffer before you use them. You can do this with the following program line.

The number in brackets is the number of 'ticks' (one hundredths of a second) which BBC BASIC (Z80) will wait for a key to be pressed. After this time, BBC BASIC (Z80) will give up and return -1 or a null string. The number of 'ticks' may have any value between 0 and 32767.

A statement to input values from the console input channel (usually keyboard).

If items are not immediately preceded by a printable prompt string (even if null) then a '?' will be printed as a prompt. If the variable is not separated from the prompt string by a comma, the '?' is not printed. In other words: no comma - no question mark.

Items A, B, C, D$ in the above example can have their answers returned on one to four lines, separate items being separated by commas. Extra items will be ignored.

Then WHO ARE YOU? is printed (the question mark comes from the comma) and W$ is input, then NAME is printed and R$ is input (no comma - no '? ').

When the <Enter> key is pressed to complete an entry, a new-line is generated. BBC BASIC has no facility for suppressing this new-line, but the TAB function can be used to reposition the cursor. For example,

will position the cursor at column 0 of line 5 and print the prompt Name ?. After the name has been entered the cursor will be positioned at column 20 on the same line and Age ? will be printed. When the age has been entered the cursor will move to the next line.

The statement

is exactly equivalent to

Leading spaces will be removed from the input line, but not trailing spaces. If the input string is not completely numeric, it will make the best it can of what it is given. If the first character is not numeric, 0 will be returned. Neither of these two cases will produce an error indication. Consequently, your program will not abort back to the command mode if a bad number is input. You may use the EVAL function to convert a string input to a numeric and report an error if the string is not a proper number or you can include your own validation checks.

Strings in quoted form are taken as they are, with a possible error occurring for a missing closing quote.

A semicolon following a prompt string is an acceptable alternative to a comma.

A statement of identical syntax to INPUT which uses a new line for each item to be input. The item input is taken as is, including commas, quotes and leading spaces.

A statement which reads data in internal format from a file and puts them in the specified variables. INPUT# is normally used with a file or device opened with OPENIN, OPENUP or OPENOUT, but may alternatively be used with the AUX device (usually a serial port) which has the 'permanently open' handle = 3.

It is possible to read past the end-of-file without an error being reported. You should always include some form of check for the end of the file.

READ# can be used as an alternative to INPUT#.

See the Disk Files section for more details and numerous examples of the use of INPUT#.

A function which returns the position of a sub-string within a string, optionally starting the search at a specified place in the string. The leftmost character position is 1. If the sub-string is not found, 0 is returned.

The first string is searched for any occurrence of the second string.

There must not be any spaces between INSTR and the opening bracket.

You can use this function for validation purposes. If you wished to test A$ to see if was one of the set 'FRED BERT JIM JOHN', you could use the following:

The character used to separate the items in the set must be excluded from the characters possible in A$. One way to do this is to make the separator an unusual character, say CHR$(127).

A function truncating a real number to the lower integer.

This function converts a real number (one with a decimal part) to the nearest integer (whole number) less than the number supplied. Thus,

gives 14, whereas

gives -15.

A string function which returns the left 'num' characters of the string. If there are insufficient characters in the source string, all the characters are returned.

There must not be any spaces between LEFT$ and the opening bracket.

For example,

would print

A function which returns the length of the argument string.

This function 'counts' the number of characters in a string. For example,

would set 'length' to 15 since the string consists of the 12 characters of BBC BASIC (Z80) followed by three spaces.

LEN is often used with a FOR----NEXT loop to 'work down' a string doing something with each letter in the string. For example, the following program looks at each character in a string and checks that it is a valid hexadecimal numeric character.

LET is an optional assignment statement.

LET is not permitted in the assignment of the pseudo-variables LOMEM, HIMEM, PAGE, PTR# and TIME.

LET was mandatory in early versions of BASIC. Its use emphasised that when we write

we don’t mean to state that X equals X+4 - it can’t be, but rather 'let X become equal to what it was plus 4':

Most modern versions of BASIC allow you to drop the 'LET' statement. However, if you are writing a program for a novice, the use of LET makes it more understandable.

A command which causes lines of the current program to be listed out to the currently selected output stream (see *OPT) with the automatic formatting options specified by LISTO.

A hyphen is an acceptable alternative to a comma.

When using the normal screen output (*OPT 0), the listing may be paused by pressing the <Ctrl> and <Shift> keys together. You can also set the output to paged mode by typing ^N (VDU 14). In this mode, the screen output will halt at the end of each page until the <Shift> key is pressed. Paged mode may be turned off by typing ^O (VDU 15).

Escape will abort the listing.

You can cause the listing to be printed by pressing ^P. Printing can be stopped by pushing ^P a second time (it’s a 'toggle' action).

LIST may be included within a program, but it will exit to the command mode on completion of the listing.

A command which causes lines of the current program which contain the specified string to be listed to the currently selected output stream (see *OPT).

You can specify the range of line numbers to be listed in a similar manner to LIST. For example,

Will list all the lines between 100 and 2500 which contain the keyword 'DEF'

Keywords are tokenised before the search begins. Consequently, you can use LIST IF to find lines with particular commands in them.

LIST IF is very useful for locating the lines in a program which define or use functions or procedures.

A command which controls the appearance of a LISTed program. The command controls the setting of the three least significant bits of the format control byte which can, therefore, be set to an integer 0 to 7 (0=all three bits 0, 7=all three bits 1).

A function giving the natural logarithm of its argument.

This function gives the logarithm to the base 'e' of its argument. The 'natural' number, 'e', is approximately 2.71828183.

Logarithms are 'traditionally' used for multiplication (by adding the logarithms) and division (by subtracting the logarithms). For example,

will calculate 2.5*2 by adding their natural logarithms and print the answer.

A command which loads a new program from a file and CLEARs the variables of the old program. The program file must be in 'internal' (tokenised) format.

File names must conform to the standard CP/M-80 format. However, if no extension is given, .BBC is assumed. If no disk and/or path are given, the current disk and/or path are assumed. See the Operating System Interface section for a more detailed description of valid file names.

You use LOAD to bring a program in a disk file into memory. The keyword LOAD should be followed by the name of the program file. If the program file is in the current directory, only the file name needs to be given. If the program is not in the current directory, its full drive, path and file name must be specified. For example:

would load the program 'demo.bbc' from the directory 'bbcprogs' on drive a:.

A statement to declare variables for local use inside a function (FN) or procedure (PROC). A null list of variables is not permitted.

LOCAL saves the values of its arguments in such a way that they will be restored at '=' or ENDPROC.

If a function or a procedure is used recursively, the LOCAL variables will be preserved at each level.

The LOCAL variables are initialised to zero/null.

See the keyword ON ERROR LOCAL for details of local error trapping.

A function giving the base-10 logarithm of its argument.

This function calculates the common (base 10) logarithm of its argument. Inverse logarithms (anti-logs) can be calculated by raising 10 to the power of the logarithm. For example, if x=LOG(y) then y=10^x.

Logarithms are 'traditionally' used for multiplication (by adding the logarithms) and division (by subtracting the logarithms). For example,

A pseudo-variable which controls where in memory the dynamic data structures are to be placed. The default is TOP, the first free address after the end of the program.

Normally, dynamic variables are stored in memory immediately after your program. (See the Annex entitled Format of Program and Variables in Memory.) You can change the address where BBC BASIC (Z80) starts to store these variables by changing LOMEM.

USE WITH CARE. Changing LOMEM in the middle of a program causes BBC BASIC (Z80) to lose track of all the variables you are using.