OSBYTE &81

OSBYTE &81 (129) - Read key with time limit

 On entry: XY=16-bit argument
 On exit:  XY=returned character or state
           Cy=when waiting for a character, no character returned

Description

OSBYTE &81 waits for a character from the current input stream, or tests for a keypress on the keyboard, or returns a value indicating the host machine type. The argument passed in XY is a signed 16-bit value. Positive values (&0000-&7FFF) are a timeout in centiseconds to wait for a character. Negative values (&8000-&FFFF) test for keyboard keypresses, machine type, and any extensions. These are known as negative INKEY numbers.

OSBYTE &81 is called by INKEY and INKEY$ in BBC BASIC, and equivalent calls in other languages and applications.

Wait for input character

 On entry: Y<128 - XY=centisecond timeout - INKEY(0) to INKEY(32767)
 On exit:  Cy=0, Y=0, X=character read
           Cy=1, Y=255 timed out
           Cy=1, Y=27  ESCAPE was pressed
 The caller can test for either Y=0 or Cy=0 for a valid returned character.
 
 Example:  .loop
           JSR tick            :\ Do some processing
           LDY #0:LDX #200     :\ timeout=200cs
           LDA #129:JSR OSBYTE :\ Wait for character
           BCS loop            :\ Loop if no key pressed

Scan for a particular key

 On entry: Y=&FF
           X=&80-&FF negative INKEY number - INKEY(-1) to INKEY(-128)
 On exit:  XY=&0000 - key not pressed
           XY=&FFFF - key pressed

Scan for a range of keys

 On entry: Y=&FF
           X=&01-&7F negative INKEY number - INKEY(-129) to INKEY(-255)
 On exit:  XY=&00FF - key not pressed
           XY=&00nn - key pressed, returns key number
 
 This call scans for a key pressed starting at the passed key number. It is
 rarely implemented.

Check machine type

Depending on what the program needs to know, OSBYTE &00 is usually the more appropriate call to make.

 On entry: Y=&FF
           X=&00
 On entry: X=A value indentifying the subtype of the host (I/O) machine type:
           X=&00 BBC A/B with OS 0.10
           X=&00 RM Nimus
           X=&01 Acorn Electron OS
           X=&FF BBC Micro OS 1.00/1.20/1.23, Reuters OS R0.3 with *UK
           X=&FE BBC Micro (American OS A1.0), Reuters OS R0.3 with *US
           X=&FE NetBSD
           X=&FD Master 128 MOS 3.20/3.50
           X=&FC BBC Micro (West German MOS) - see note
           X=&FC Windows 32
           X=&FB BBC B+ 64/128 (OS 2.00)
           X=&FB Beos (Brandy Basic)
           X=&FA Acorn Business Computer OS 1.00/2.00
           X=&FA Cambridge Workstation OS 2.10
           X=&FA DOS with DJGPP extender (Brandy Basic)
           X=&F9 Communicator
           X=&F9 Linux
           X=&F8 MacOS X (Brandy Basic)
           X=&F7 Master ET MOS 4
           X=&F7 FreeBSD
           X=&F6 OpenBSD
           X=&F5 Master Compact MOS 5
           X=&F5 Amiga (Brandy Basic)
           X=&F4 Master 128 MOS 3.26
           X=&F4 GNU FreeBSD (Brandy Basic)
           X=&F3 GNU (Brandy Basic)
           X=&Ex Spectrum
             X=&E0 ZX Spectrum
                   (INKEY-256 AND &F0)=&E0 gives TRUE for ZX Spectrum hardware
           X=&Dx Amstrad 464/664/6128, etc.
                   (INKEY-256 AND &F0)=&D0 gives TRUE for Amstrad CPC hardware
           X=&Cx Commodore 64/64+/128, etc.
                   (INKEY-256 AND &F0)=&C0 gives TRUE for Commodore hardware
           X=&Bx PDP11 Unix
             X=&B7 PDP11 Unix Version 7
             X=&B6 PDP11 Unix Version 6
             X=&B5 PDP11 Unix Version 5
                   (INKEY-256 AND &F0)=&B0 gives TRUE for PDP11 hardware
           X=&Ax ARM-based systems
             X=&A0 Arthur 1.20
             X=&A1 RISC OS 2.00
             X=&A2 RISC OS 2.01
             X=&A3 RISC OS 3.0x
             X=&A4 RISC OS 3.1x
             X=&A5 RISC OS 3.50
             X=&A6 RISC OS 3.60
             X=&A7 RISC OS 3.7x
             X=&A8 RISC OS 4.0x
             X=&A9 RISC OS 4.3x
             X=&AA RISC OS 5.xx
             X=&AE RISC OS Pyromaniac
             X=&AF Springboard - an ARM-based development system plugged into
                   a PC)
                   (INKEY-256 AND &F0)=&A0 gives TRUE for ARM hardware
           X=&8x Texas Instruments Calculator
             X=&83 TI-83+(SE)
             X=&84 TI-84+(SE)
                   (INKEY-256 AND &F0)=&80 gives TRUE for TI Calculator hardware
           X=&68 6809 system
           X=&63 6309 system
           X=&73 BBC BASIC on SDL abstraction from C source (ie ASC"s")
           X=&57 BBC BASIC for Windows (ie ASC"W")
           X=&53 BBC BASIC SDL abstraction from assembly language source
                 (ie ASC"S")
                 (INKEY-256 AND &DB)=&53 gives TRUE for R.T.Russell's
                 BBC BASIC for Windows/SDL/etc
           X=&4D Matrix Brandy BASIC (ie ASC"M") for all builds from v1.22.6
                 except RISC OS.
 
 The known examples of German BBC MOS return X=&FF.

Extensions

The parameter to OSBYTE &81 is a 16-bit number. The standard implementation interprets that as:

 <&8000   - wait for keypress
 &FF00+nn - scan for BBC keypress
 &FF00    - return host machine type

A parameter of &8000-&FEFF is undefined. Some systems extend OSBYTE &81 or INKEY as follows:

 &FE00+nn - scan for low level DOS/Window VK_xxxx keypress
            (cZ80Tube, console library)
 &FC00+nn - scan for low level SDL1.2 SDK_xxx keypress
            (Brandy Basic SDL builds)
 &8000+nn - wait for keypress, return 16-bit character code
            (cZ80Tube, console library)

See Also

• INKEY
• OSBYTE &00
• What BASIC is running
• Negative INKEY numbers
• Keyboard
• http://mdfs.net/Docs/Comp/BBC/Osbyte80
• http://mdfs.net/Docs/Comp/Acorn/HostVals
• http://mdfs.net/Docs/Comp/Acorn/Hosts

---

Jgharston 21:56, 26 May 2009 (UTC) Jgharston (talk) 05:20, 23 June 2018 (CEST) Jgharston (talk) 22:09, 25 August 2019 (CEST) Jgharston (talk) 20:03, 16 February 2020 (CET) Jgharston (talk) 07:08, 12 April 2020 (CEST) Jgharston (talk) 00:46, 19 May 2021 (CEST)