OSWORD &0F

OSWORD &0F (15): Write Real-Time clock

On entry:
 XY?0=length of data at XY+1
 XY?0=1   Single-character command at XY+1
 XY?0=3   Set alarm XY+1=3-byte BCD alarm block
 XY?0=3   Set timezone offset from XY+1="TZN"
 XY?0=5   Set from  XY+1=5-byte centisecond time
 XY?0=6   Set timezone offset from XY+1="TZN+NN" or XY+1="TZN-NN"
 XY?0=7   Set from  XY+1=7-byte BCD date block, year 1980-2079
 XY?0=7   (provisional) Adjust by centisecond adjust, XY+1="S+ss.cc" or "S-ss.cc"
 XY?0=8   Set from  XY+1=8-byte BCD date block with century
 XY?0=8   Set from  XY+1="hh:mm:ss"
 XY?0=11  Set from  XY+1="dd mmm yyyy"
 XY?0=15  Set from  XY+1="DDD,dd mmm yyyy"
 XY?0=20  Set from  XY+1="dd mmm yyyy.hh:mm:ss"
 XY?0=24  Set from  XY+1="DDD,dd mmm yyyy.hh:mm:ss"

The caller should simply store the length of the passed data at XY?0 and store the passed data at XY+1. The caller must not put any interpretation on the data and length it passes, that is entirely the responsibility of the code that implements the call, not the caller.

Where different subcalls have the same length byte, the calls are distinguished by the data block being either BCD or text. For instance:

• 3,TIME - each byte is &00-&59 or &C0-&FF
• 3,"TZN" - each byte is &40-&7F
• 7,DATETIME - XY+2 is BCD &01-&12 valid month value
• 7,"S+ss.cc" - XY+2 is printable character
• 8,DATETIME - byte XY?3 is BCD &00-&1F valid date value
• 8,"hh:mm:ss" - byte XY?3 is printable character

On exit:

The only defined exit state is that unsupported calls should leave the control block unchanged, and known implementations leave the control block unchanged after successful calls. Known implementations also leave the control block unchanged after unsuccessful calls.

An appropriate extension would be for supported calls to modify the returned control block if passed invalid data, such as 8,"99:88:77" which is an invalid time.

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.

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-&59
 +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-&59
 +6 minute  &00-&59
 +7 second  &00-&59

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

Other subcalls

XY+0=1: 1-byte command:
        XY+1="S" Syncronise clock. Waits for seconds to roll over, then
        returns without changing clock.
XY?0=7  Adjust by centisecond adjust
        XY+1="S+ss.cc" or "S-ss.cc"

Calling from BASIC

 REM X%=>control block, Y%=X%DIV256
 REM T$=string
 :
 X%?0=LEN(T$):$(X%+1)=T$
 A%=15:CALL OSWORD

Implementation

On a system without a Real Time Clock, the MOS passes OSWORD 15 to sideways ROMs for support. Implementations should ignore unsupported subcodes and pass them on. Writing invalid data should be silently swallowed, what the implementation does with invalid data is implementation specific. Some implementations may write the data as is, so TIME$="14:90:00" sets the time to 14:90:00. Some implementations will wrap, so TIME$="14:90:00" sets the time to 15:30:00. Undefined behaviour is undefined.

Master MOS

The Master MOS 3 and MOS 4 implements subcalls 8,15,24. Unimplemented subcalls are swallowed and not passed on.

Master Compact

The Master MOS 5 passes all calls to sideways ROMs.

ANFS

ANFS does not implement any OSWORD &0F calls, only OSWORD &0E calls to read the RTC. (add list)

SoftRTC

The SoftRTC module stores the time and date with the system TIME timer. It implements subcalls 7,8,11,15,20,24. The SoftRTC module included in HADFS sets the date with *SETDATE. Unimplemented subcalls are passed on.

PMS Clock

The PMS Clock ignores the subcode and instead decides what to set based on the first few characters of the data block. If there is a comma, it assumes a 24-byte time&date string. If there is a colon, it assumes an 8-byte time string.

TicToc ROM

TicToc ignores the subcode and instead decides what to set based on the first character of the data block. If it is a digit, it assumes an 8-byte time string. If it is a letter, it assumes a 24-byte time&date string.

RISC OS

Implements subcodes 5,8,15,24. The century is read from the system configuration.

Suitable possible extensions

Calls to OSWORD &0F are simply length,string, so additional calls can be implemented for suitable parameters. These are some possibilities.

  1,nn             - single-character command
  2,nn,nn          - ?
  4,"yyyy"         - set year
  6,"xxxxxx"       - ?
  9,"xxxxxxxxx"    - ?
 10,"A=hh:mm:ss"   - set alarm

Notes

Have not yet found information to document implementations supporting turning alarm on/off, and reading alarm setting.

See Also

• OSWORD &0E
• https://mdfs.net/Docs/Comp/BBC/Osword/RTCOswords
• https://stardot.org.uk/forums/viewtopic.php?t=28607

Jgharston 12:57, 26 May 2009 (UTC) Jgharston (talk) 00:16, 7 January 2023 (CET) Jgharston (talk) 21:04, 7 February 2023 (CET) Jgharston (talk) 02:34, 16 February 2023 (CET)