Difference between revisions of "OSWORD &0E"

From BeebWiki
Jump to: navigation, search
(Added subcode 3,4 and implementation details.)
m (Correct hour range.)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:OSWORD]]
 
[[Category:OSWORD]]
−
OSWORD &0E (14) - Reads CMOS clock
+
{{PageTitle|OSWORD &0E (14): Read Real-Time clock}}
−
 
+
__NOTOC__
 +
===Summary===
 
  On entry:
 
  On entry:
 
   XY?0=function code
 
   XY?0=function code
−
 
+
  XY?0=0+n use 7-bit BCD date block
−
  0 - Return clock value as string
+
  XY?0=8+n use 8-bit BCD date block
−
   On exit:
+
  XY?0=0 XY?0=8  Read as 25-character string
−
  XY+0..23=CR-terminated string in form
+
   XY?0=1  XY?0=9  Read as 7- or 8-byte BCD block
−
  "Day,DD Mon Year.HH:MM:SS"
+
  XY?0=2  XY?0=10 Convert 7- or 8-byte BCD block at XY+1 to string
−
 
+
   XY?0=3          Read as 5-byte centisecond time
−
  1 - Return BCD clock value.
+
  XY?0=3          Read 25-character string from file server (ANFS 4.2x)
−
   On exit:
+
  XY?0=4          Read BCD clock value from file server (ANFS)
−
  XY?0=year (&00-&99)
+
  XY?0=4          Return "hh:mm:ss DDD dd-mm-yy tt",CR
−
  XY?1=month (&01-&12)
+
                  where tt is temperature. (I2C Control ROM)
−
  XY?2=date (&01-&31)
+
  XY?0=5
−
  XY?3=day of week (&01-&07, Sun-Sat or &00, not returned)
+
  XY?0=6
−
  XY?4=hours (&00-&23)
+
  XY?0=7
−
  XY?5=minutes (&00-&59)
+
On exit:
−
  XY?6=seconds (&00-&59)
+
  XY?x=if subcall unsupported, control block unchanged
−
    
+
  XY?x=if subcall supported, control block modified
−
   A year value of &80-&99 represents 1980-1999, a value of
+
===Calls===
−
   &00-&79 represents 2000-2079.
+
On entry:
−
 
+
  XY?0=0:   Return clock value as string
−
  2 - Convert BCD to string.
+
   XY?0=8:  Return clock value as string
−
   On entry:
+
On exit:
−
  XY+1..7=BCD value as with subfunction 1
+
  XY+0..24:  CR-terminated string
−
  On exit:
+
            Note: some implementations do not return the CR, so the
−
  XY+1..25=CR-terminated string as with subfunction 0
+
            caller should manually add a CR with XY?24=13.
−
 
+
−
  3 - Return 5-byte centisecond clock value (where supported)
+
On entry:
−
  On exit:
+
  XY?0=1:  Return 7-byte BCD clock value
−
  XY?0..4=number of centiseconds since 00:00:00 01-Jan-1900
+
   XY?0=9:  Return 8-byte BCD clock value
−
 
+
On exit:
−
  3 - Return clock value as string from file server (ANFS 4.2x)
+
  XY+0..6:  7-byte BCD clock value
−
  On exit:
+
  XY+0..7:  8-byte BCD clock value
−
  XY+0..23=CR-terminated string in form
+
−
  "Day,DD Mon Year.HH:MM:SS"
+
  On entry:
−
 
+
  XY?0=2:  Convert 7-bit BCD to string
−
  4 - Return BCD clock value from file server (ANFS).
+
  XY+1..7:  7-byte BCD clock value
−
   On exit:
+
   XY?0=10: Convert 8-bit BCD to string
−
  XY?0=year (&00-&99)
+
  XY+1..8:  8-byte BCD clock value
−
  XY?1=month (&01-&12)
+
On exit:
−
  XY?2=date (&01-&31)
+
  XY+0..24: CR-terminated string
−
  XY?3=day of week (&00, not returned)
+
−
   XY?4=hours (&00-&23)
+
  On entry:
−
  XY?5=minutes (&00-&59)
+
  XY?0=3:  Return 5-byte centisecond clock value
−
  XY?6=seconds (&00-&59)
+
On exit:
−
    
+
  XY?0..4:  Number of centiseconds since 00:00:00 01-Jan-1900
−
   A year value of &80-&99 represents 1980-1999, a value of
+
−
   &00-&79 represents 2000-2079.
+
  On entry:
−
 
+
  XY?0=3:  Return clock value as string from file server (ANFS 4.2x)
−
  ? - Return BCD time/date/temperature
+
On exit:
−
 
+
  XY+0..24: CR-terminated string
−
  ? - Return time/date/temperature string
+
 +
On entry:
 +
  XY?0=4:  Return BCD clock value from file server (ANFS).
 +
On exit:
 +
  XY+0..6:  7-byte BCD clock value
 +
 +
On entry:
 +
   XY?0=4:  Return time, date and temperature string (I2C).
 +
On exit:
 +
  XY+0..24: CR-terminated string
 +
===Data format===
 +
The date string format is "DDD,dd mmm yyyy.hh:mm:ss". The punctuation is normally
 +
irrelevant, the position of the component values is fixed.
 +
 +
The I2C temperature string format is "hh:mm:ss DDD dd-mm-yy tt" where tt is the
 +
temperature.
 +
 +
7-byte BCD date block format:
 +
  +0 year   &00-&99 year is 1980-2079
 +
  +1 month   &01-&12
 +
  +2 date   &01-&31
 +
  +3 day     &01-&07 Sun-Sat or &00 for unsupported
 +
  +4 hour   &00-&23
 +
  +5 minute  &00-&59
 +
  +6 second  &00-&59
 +
 +
8-byte BCD date block format:
 +
   +0 century &00-&99
 +
   +1 year   &00-&99
 +
  +2 month  &01-&12
 +
  +3 date    &01-&31
 +
  +4 day    &01-&07 Sun-Sat or &00 for unsupported
 +
  +5 hour    &00-&23
 +
   +6 minute  &00-&59
 +
  +7 second  &00-&59
 +
 +
  3-byte BCD alarm block format:
 +
  +0 hour    &00-&23 or &C0-&FF for 'any'
 +
  +1 minute  &00-&59 or &C0-&FF for 'any'
 +
  +2 second &00-&59 or &C0-&FF for 'any'
 +
==Calling from BASIC==
 +
REM X%=>control block, Y%=X%DIV256
 +
:
 +
REM Read string:
 +
?X%=0:A%=14:CALL OSWORD:IF ?X%=0 THEN T$="" ELSE X%?24=13:T$=$X%
 +
:
 +
REM Read BCD:
 +
!X%=1:A%=14:CALL OSWORD:IF !X%=1 THEN unsupported ELSE data returned
  
 
==Implementation==
 
==Implementation==
 
On a system without a Real Time Clock, the MOS passes OSWORD 14 to sideways
 
On a system without a Real Time Clock, the MOS passes OSWORD 14 to sideways
 
ROMs for support.
 
ROMs for support.
 +
 +
===Master MOS===
 +
The Master MOS 3 and MOS 4 implements subcalls 0,1,2. Unsupported subcodes are
 +
silently swallowed and not passed on. Unpatched versions always consistantly
 +
return the year in the date string as 19xx.
 +
 +
===Master Compact===
 +
The Master MOS 5 implements subcall 2 to convert a BCD block to a string.
 +
It passes all other calls to sideways ROMs. If there is no response for
 +
subcall 0 and 1 it returns a default value of 31 Dec 1999, 23:59:59.
  
 
===ANFS===
 
===ANFS===
 
Master ANFS 4.2x implements subcalls 0,1,3,4 and calls OSWORD 14,2 to
 
Master ANFS 4.2x implements subcalls 0,1,3,4 and calls OSWORD 14,2 to
 
convert the result of subcall 0 and 3 to a string. BBC ANFS 4.0x and 4.1x
 
convert the result of subcall 0 and 3 to a string. BBC ANFS 4.0x and 4.1x
−
only implements OSWORD 14,4.
+
only implements subcall 4.
  
 
The ANFS implementation fails in a predictable manner with dates after
 
The ANFS implementation fails in a predictable manner with dates after
Line 68: Line 126:
 
year is (year-1981) AND 15. The date can be repaired across the whole date
 
year is (year-1981) AND 15. The date can be repaired across the whole date
 
range with:
 
range with:
−
 
 
   date =BCDtoBIN(returned_date) AND 31
 
   date =BCDtoBIN(returned_date) AND 31
 
   month=BCDtoBIN(returned_month)
 
   month=BCDtoBIN(returned_month)
−
   year =(BCDtoBIN(returned_date) AND &E0) DIV 2 + BCDtoBIN(returned-year) + 1900
+
   year =(BCDtoBIN(returned_date) AND &E0) DIV 2 + BCDtoBIN(returned-year)+1900
  
 
===SoftRTC===
 
===SoftRTC===
−
The SoftRTC module (included in HADFS) implements subcalls 0,1,2 with the
+
The SoftRTC module stores the time and date with the system TIME timer. It
−
date set with *SETDATE and the time being calculated from TIME.
+
implements subcalls 0,1,2 and 8,9,10. The SoftRTC module included in HADFS
 +
only implements subcalls 0,1,2 with the date set with *SETDATE.
 +
 
 +
===PMS Clock ROM===
 +
PMS Clock implements subcalls 0,1,2.
 +
 
 +
===I2C Control ROM===
 +
The I2C Control ROM implements subcode 4 (clashing with ANFS).
 +
 
 +
===TicToc ROM===
 +
TicToc returns a 24-byte time&date string from every call to OSWORD &14,
 +
completely ignoring the subcode.
 +
 
 +
===RISC OS===
 +
Implements subcodes 0,1,2,3. Subcode 3 clashes with ANFS. The returned century
 +
is that set in the system configuration.
 +
 
 +
===Notes===
 +
Several implementations implement clashing subcodes.
 +
 
 +
==Y2K Issues==
 +
Some RTC systems always consistantly return the year in the date string as 19xx.
 +
This can be repaired with:
 +
  Read time string to T$
 +
  IF MID$(T$,14,1)<"8":T$=LEFT$(T$,11)+"20"+MID$(T$,14)
  
 
==See Also==
 
==See Also==
 
* [[OSWORD &0F]]
 
* [[OSWORD &0F]]
−
* http://mdfs.net/Docs/Comp/BBC/Oswords
+
* https://mdfs.net/Docs/Comp/BBC/Osword/RTCOswords
  
 
[[User:Jgharston|Jgharston]] 12:56, 26 May 2009 (UTC)
 
[[User:Jgharston|Jgharston]] 12:56, 26 May 2009 (UTC)
−
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 14:36, 23 January 2019 (CET)
+
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 06:45, 12 April 2020 (CEST)
 +
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 23:56, 6 January 2023 (CET)

Latest revision as of 14:54, 5 May 2024

OSWORD &0E (14): Read Real-Time clock

Summary

On entry:
 XY?0=function code
 XY?0=0+n use 7-bit BCD date block
 XY?0=8+n use 8-bit BCD date block
 XY?0=0  XY?0=8   Read as 25-character string
 XY?0=1  XY?0=9   Read as 7- or 8-byte BCD block
 XY?0=2  XY?0=10  Convert 7- or 8-byte BCD block at XY+1 to string
 XY?0=3           Read as 5-byte centisecond time
 XY?0=3           Read 25-character string from file server (ANFS 4.2x)
 XY?0=4           Read BCD clock value from file server (ANFS)
 XY?0=4           Return "hh:mm:ss DDD dd-mm-yy tt",CR
                  where tt is temperature. (I2C Control ROM)
 XY?0=5
 XY?0=6
 XY?0=7
On exit:
 XY?x=if subcall unsupported, control block unchanged
 XY?x=if subcall supported, control block modified

Calls

On entry:
 XY?0=0:   Return clock value as string
 XY?0=8:   Return clock value as string
On exit:
 XY+0..24:  CR-terminated string
            Note: some implementations do not return the CR, so the
            caller should manually add a CR with XY?24=13.

On entry:
 XY?0=1:  Return 7-byte BCD clock value
 XY?0=9:  Return 8-byte BCD clock value
On exit:
 XY+0..6:  7-byte BCD clock value
 XY+0..7:  8-byte BCD clock value

On entry:
 XY?0=2:  Convert 7-bit BCD to string
 XY+1..7:  7-byte BCD clock value
 XY?0=10: Convert 8-bit BCD to string
 XY+1..8:  8-byte BCD clock value
On exit:
 XY+0..24: CR-terminated string

On entry:
 XY?0=3:   Return 5-byte centisecond clock value
On exit:
 XY?0..4:  Number of centiseconds since 00:00:00 01-Jan-1900

On entry:
 XY?0=3:  Return clock value as string from file server (ANFS 4.2x)
On exit:
 XY+0..24: CR-terminated string

On entry:
 XY?0=4:  Return BCD clock value from file server (ANFS).
On exit:
 XY+0..6:  7-byte BCD clock value

On entry:
 XY?0=4:  Return time, date and temperature string (I2C).
On exit:
 XY+0..24: CR-terminated string

Data format

The date string format is "DDD,dd mmm yyyy.hh:mm:ss". The punctuation is normally
irrelevant, the position of the component values is fixed.

The I2C temperature string format is "hh:mm:ss DDD dd-mm-yy tt" where tt is the
temperature.

7-byte BCD date block format:
 +0 year    &00-&99 year is 1980-2079
 +1 month   &01-&12
 +2 date    &01-&31
 +3 day     &01-&07 Sun-Sat or &00 for unsupported
 +4 hour    &00-&23
 +5 minute  &00-&59
 +6 second  &00-&59

8-byte BCD date block format:
 +0 century &00-&99
 +1 year    &00-&99
 +2 month   &01-&12
 +3 date    &01-&31
 +4 day     &01-&07 Sun-Sat or &00 for unsupported
 +5 hour    &00-&23
 +6 minute  &00-&59
 +7 second  &00-&59

3-byte BCD alarm block format:
 +0 hour    &00-&23 or &C0-&FF for 'any'
 +1 minute  &00-&59 or &C0-&FF for 'any'
 +2 second  &00-&59 or &C0-&FF for 'any'

Calling from BASIC

REM X%=>control block, Y%=X%DIV256
:
REM Read string:
?X%=0:A%=14:CALL OSWORD:IF ?X%=0 THEN T$="" ELSE X%?24=13:T$=$X%
:
REM Read BCD:
!X%=1:A%=14:CALL OSWORD:IF !X%=1 THEN unsupported ELSE data returned

Implementation

On a system without a Real Time Clock, the MOS passes OSWORD 14 to sideways ROMs for support.

Master MOS

The Master MOS 3 and MOS 4 implements subcalls 0,1,2. Unsupported subcodes are silently swallowed and not passed on. Unpatched versions always consistantly return the year in the date string as 19xx.

Master Compact

The Master MOS 5 implements subcall 2 to convert a BCD block to a string. It passes all other calls to sideways ROMs. If there is no response for subcall 0 and 1 it returns a default value of 31 Dec 1999, 23:59:59.

ANFS

Master ANFS 4.2x implements subcalls 0,1,3,4 and calls OSWORD 14,2 to convert the result of subcall 0 and 3 to a string. BBC ANFS 4.0x and 4.1x only implements subcall 4.

The ANFS implementation fails in a predictable manner with dates after 1996. The returned date is ((year-1981) DIV 16)*16+date and the returned year is (year-1981) AND 15. The date can be repaired across the whole date range with: 

 date =BCDtoBIN(returned_date) AND 31
 month=BCDtoBIN(returned_month)
 year =(BCDtoBIN(returned_date) AND &E0) DIV 2 + BCDtoBIN(returned-year)+1900

SoftRTC

The SoftRTC module stores the time and date with the system TIME timer. It implements subcalls 0,1,2 and 8,9,10. The SoftRTC module included in HADFS only implements subcalls 0,1,2 with the date set with *SETDATE.

PMS Clock ROM

PMS Clock implements subcalls 0,1,2.

I2C Control ROM

The I2C Control ROM implements subcode 4 (clashing with ANFS).

TicToc ROM

TicToc returns a 24-byte time&date string from every call to OSWORD &14, completely ignoring the subcode.

RISC OS

Implements subcodes 0,1,2,3. Subcode 3 clashes with ANFS. The returned century is that set in the system configuration.

Notes

Several implementations implement clashing subcodes.

Y2K Issues

Some RTC systems always consistantly return the year in the date string as 19xx. This can be repaired with: 

 Read time string to T$
 IF MID$(T$,14,1)<"8":T$=LEFT$(T$,11)+"20"+MID$(T$,14)

See Also

Jgharston 12:56, 26 May 2009 (UTC) Jgharston (talk) 06:45, 12 April 2020 (CEST) Jgharston (talk) 23:56, 6 January 2023 (CET)

Retrieved from "http://beebwiki.mdfs.net/index.php?title=OSWORD_%260E&oldid=4648"