From BeebWiki
Revision as of 02:43, 10 February 2022 by Jgharston (talk | contribs) (Slight tweek.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

ADVAL is a BASIC function read an input device or examine a buffer.

Availability Present in all original versions of BBC BASIC.
Syntax <numeric> = ADVAL<numeric>
Token (hex) 97 (function)
Description Reads an input device or examines a buffer.


ADVAL calls OSBYTE &80 to read an input device (positive argument) or examine a buffer (negative argument). It returns the value from the input device, the free space in an output buffer, or the used space in an input buffer.

Reading the status of an input buffer returns 0 if there is nothing in the buffer and <>0 if there is something in the buffer, so that code of the following form can be used:

 IF ADVAL(buffer) THEN REM ReadFromBuffer

Reading the status of an output buffer returns 0 if there is no free space in the buffer and <>0 if there is free space in the buffer, so that code of the following form can be used:

 IF ADVAL(buffer) THEN REM WriteToBuffer

Defined buffer/device numbers

Argument Returns
0 b0-b7=buttons, b8-b15=last ADC channel converted
1 Analogue Channel 1/Joystick 1 X position
2 Analogue Channel 2/Joystick 1 Y position
3 Analogue Channel 3/Joystick 2 X position
4 Analogue Channel 4/Joystick 2 Y position
5 Mouse X boundary
6 Mouse Y boundary
7 Mouse X position
8 Mouse Y position
9 Mouse button state, b0=Left, b1=Middle, b2=Right
128-n Low-level read from buffer n-1
127 (128-1) 16-bit GET (cZ80Tube, PDPTube, Brandy Basic)
-1 Keyboard input buffer
-2 Serial input buffer
-3 Serial output buffer
-4 Printer output buffer
-5 Sound output buffer 0
-6 Sound output buffer 1
-7 Sound output buffer 2
-8 Sound output buffer 3
-9 Speech output buffer
-10 Mouse input buffer
-11 MIDI input buffer
-12 MIDI output buffer


If an unknown device or buffer is examined, then the call should be passed to sideways ROMs as an Unknown OSBYTE service call.

Unfortunately, BBC MOSes other than MOS 5 (Master Compact) do not actually do this, and return undefined values for unimplemented calls. Sideways ROM code must intercept BYTEV in order to support additional calls.

RISC OS also does not actually do this, fatally generating a Bad Command error instead of returning. This causes programs to fail if a device is not present, rather than simply not doing anything.


Most mouse drivers do not implement calls 5, 6 and 9. The VFS Videodisk Filing System ROM used with the Domesday System implements 5, 6 and 9. The mouse buttons are more usually read with INKEY-10, INKEY-11 and INKEY-12. 8-bit systems rarely implement a mouse buffer.


32-bit systems usually use a sound system that does not use the sound output buffers.

Jgharston 00:30, 2 January 2008 (UTC)