Difference between revisions of "OSBYTE &81"

From BeebWiki
Jump to: navigation, search
m (Added PDP11 Unix Version 5.)
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
[[Category:OSBYTE]]
+
[[Category:OSBYTE]]__NOTOC__
OSBYTE &81 (129) - Read Key with Time Limit or Machine Type. Called by BASIC's =[[INKEY]] function.
+
{{PageTitle|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
  
    Action: Read key with time limit
+
==Description==
    On entry: X=0..255
+
[[OSBYTE &81]] waits for a character from the current input stream,
              Y=0..127
+
or tests for a keypress on the keyboard, or returns a value indicating
    On exit:  Cy=0, Y=0, X=character read
+
the host machine type. The argument passed in XY is a signed 16-bit
              Cy=1, Y=255 timed out
+
value. Positive values (&0000-&7FFF) are a timeout in centiseconds to
              Cy=1, Y=27  ESCAPE was pressed
+
wait for a character. Negative values (&8000-&FFFF) test for keyboard
    The caller can test for either Y=0 or Cy=0 for a valid returned character.
+
keypresses, machine type, and any extensions. These are known as
 +
[[negative INKEY numbers]].
  
    Action: Read OS version
+
OSBYTE &81 is called by [[INKEY]] and [[INKEY$]] in BBC BASIC, and
    On entry: X=0
+
equivalent calls in other languages and applications.
              Y=255
 
    On exit:  X=value identifying the host OS
 
              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.
+
===Wait for input character===
 +
  On entry: Y<128 - XY=centisecond timeout - INKEY(0) to INKEY(32767)
 +
  On exit:  Cy=0, Y=0,  X=character : character returned
 +
            Cy=1, Y=255, X preserved : timed out
 +
            Cy=1, Y=27  X preserved : Escape key pressed
 +
  The caller can test for either Cy=0 or Y=0 for a valid returned character.
 +
  If Cy=1 or Y<>0 the contents of X should not be relied on.
 +
 
 +
  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
  
    Action: Scan for a range of keys
+
Note that Y=27 is returned for a pending Escape state regardless of what
    On entry: X=1..127 lowest internal key number to start at EOR &7F
+
actual key is the current Escape key. If Escape is returned the pending
              Y=255
+
Escape state is still pending and the caller will need to acknowledge or
    On exit:  X=internal key number pressed (or 255 for none)
+
clear it at some future point.
  
    Action: Scan for a particular key
+
===Scan for a particular key===
    On entry: X=128..255 internal key number to scan for EOR &80
+
  On entry: Y=&FF
              Y=255
+
            X=&80-&FF [[Negative INKEY numbers|negative INKEY number]] - INKEY(-1) to INKEY(-128)
    On exit: X=Y=0 for as not pressed
+
  On exit:  XY=&0000 - key not pressed
              X=Y=255 the key was being 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.00/5.10
 +
            X=&F5 Amiga (Brandy Basic)
 +
            X=&F4 Master 128 MOS 3.26
 +
            X=&F4 Master Compact MOS 5.11i
 +
            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=&50 Sega Master System (ie ASC"P")
 +
            X=&4D Matrix Brandy BASIC (ie ASC"M") for all builds from v1.22.6
 +
                  except RISC OS.
 +
            X=&2A Apple IIgs
 +
            X=&2C Apple IIc
 +
            X=&2E Apple IIe
 +
 
 +
  The known examples of German BBC MOS return X=&FF.
  
 
==Extensions==
 
==Extensions==
The parameter to OSBYTE &81 is a 16-bit number. The standard implementation interprets that as:
+
The parameter to [[OSBYTE &81]] is a 16-bit number. The standard implementation interprets that as:
 
   <&8000  - wait for keypress
 
   <&8000  - wait for keypress
 
   &FF00+nn - scan for BBC keypress
 
   &FF00+nn - scan for BBC keypress
 
   &FF00    - return host machine type
 
   &FF00    - return host machine type
  
A parameter of &8000-&FEFF is undefined. Some systems extend INKEY as follows:
+
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)
+
   &FE00+nn - scan for low level DOS/Window VK_xxxx keypress
   &FC00+nn - scan for low level SDL1.2 SDK_xxx keypress (Brandy Basic SDL builds)
+
            (cZ80Tube, console library)
   &8000+nn - wait for keypress, return 16-bit character code (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==
 
==See Also==
 
* [[INKEY]]
 
* [[INKEY]]
 +
* [[OSBYTE &00]]
 +
* [[What BASIC is running]]
 +
* [[Negative INKEY numbers]]
 +
* [[Keyboard]]
 
* http://mdfs.net/Docs/Comp/BBC/Osbyte80
 
* http://mdfs.net/Docs/Comp/BBC/Osbyte80
 
* http://mdfs.net/Docs/Comp/Acorn/HostVals
 
* http://mdfs.net/Docs/Comp/Acorn/HostVals
 
* http://mdfs.net/Docs/Comp/Acorn/Hosts
 
* http://mdfs.net/Docs/Comp/Acorn/Hosts
* [[What BASIC is running]]
+
----
* Negative INKEY numbers
 
 
 
==See Also==
 
* http://mdfs.net/Docs/Comp/BBC/Osbyte80
 
 
 
 
[[User:Jgharston|Jgharston]] 21:56, 26 May 2009 (UTC)
 
[[User:Jgharston|Jgharston]] 21:56, 26 May 2009 (UTC)
 
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 05:20, 23 June 2018 (CEST)
 
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 05:20, 23 June 2018 (CEST)
Line 118: Line 162:
 
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 20:03, 16 February 2020 (CET)
 
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 20:03, 16 February 2020 (CET)
 
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 07:08, 12 April 2020 (CEST)
 
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 07:08, 12 April 2020 (CEST)
 +
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 00:46, 19 May 2021 (CEST)

Latest revision as of 20:11, 28 January 2024

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 : character returned
           Cy=1, Y=255, X preserved : timed out
           Cy=1, Y=27   X preserved : Escape key pressed
 The caller can test for either Cy=0 or Y=0 for a valid returned character.
 If Cy=1 or Y<>0 the contents of X should not be relied on.
 
 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

Note that Y=27 is returned for a pending Escape state regardless of what actual key is the current Escape key. If Escape is returned the pending Escape state is still pending and the caller will need to acknowledge or clear it at some future point.

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.00/5.10
           X=&F5 Amiga (Brandy Basic)
           X=&F4 Master 128 MOS 3.26
           X=&F4 Master Compact MOS 5.11i
           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=&50 Sega Master System (ie ASC"P")
           X=&4D Matrix Brandy BASIC (ie ASC"M") for all builds from v1.22.6
                 except RISC OS.
           X=&2A Apple IIgs
           X=&2C Apple IIc
           X=&2E Apple IIe
 
 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


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)