RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Time and Date


Introduction

There are two basic aspects of time dealt with in this chapter: passive aspects such as reading various clock settings; and active ones, where an event occurs when a given time is reached. In this chapter, a clock is a place where a stored value is incremented on a regular basis. The time is the name of the value as it is read or written.

There are several clocks that increment every 1/100th of a second (centisecond). One of them cannot be changed except by a hard reset. This is useful for time-stamping events, such as mouse moves. Another can be changed by a program, so is useful for elapsed time calculations.

The real-time clock keeps the real-world time, and represents time in centiseconds since 00:00:00 on January 1 1900. There are calls to present this information in a number of ways. The real-time can be converted to a string with complete program control over its format.

A variety of timer events can be set up. There are SWIs that will call your application after a given delay has passed or every time that delay has elapsed. You can set up a routine to sit on the ticker vector, to enable it to be called every centisecond.

A specialised form of timer event is one that will occur every time the screen driving hardware reaches the bottom of the screen. This event is useful for flicker-free redrawing. See the chapter entitled VDU Drivers for further details.

Overview and Technical Details

There are four timers, which increment at a centisecond rate. They are:

  • the monotonic timer (read-only)
  • the system timer (read/write)
  • the interval time (read/write)
  • the real-time clock (read only in general - ie only users should change it).

Monotonic timer

A monotonic timer cannot be written, except by a hard reset or when the machine is turned on. OS_ReadMonotonicTime allows you to read this value. It is useful for time-stamping within an application, such as event times. Because it can never be changed, the order of events cannot be confused.

It is stored as a 4-byte value with least significant byte first. It is incremented every centisecond, which means that it would take nearly 500 days for it to wrap around.

System clock

The system clock is stored as a 5-byte value. Like the monotonic timer it is reset by hard resets and increments every centisecond. However it can be altered. This is useful for measuring elapsed times in an application. OS_Word 1 reads the value and OS_Word 2 writes it.

Real-time

The real-time clock is stored as a 5-byte value in the CMOS clock chip and reflects the normal usage of the word clock. That is, it stores the elapsed number of centiseconds since 00:00:00 on January 1 1900. You can set it using the Alarm application on the desktop.

Under RISC OS 2 the real-time clock is assumed to be set to local time. Under later versions, the real-time clock is assumed to be set to UTC, or Universal Time Coordinated. (This used to be called GMT, or Greenwich Mean Time.) Territory modules provide the necessary information for the kernel to convert the real-time clock value to a local time in a suitable format.

A soft copy of the real time clock is also kept by RISC OS and is used by the filing system to date-stamp files. This soft copy is updated from the CMOS clock chip following a hard reset.

String format

*Time displays the local time and date as a string. It calls OS_Word 14,0 to do so. The format of the string depends on the territory which the computer is set to use. (It is fixed in RISC OS 2, which does not support territories.) For example:

Tue,28 Mar 1989.13:25:54

5-byte format

The real-time clock can be read in the standard 5-byte format using OS_Word 14,3. This, or any, 5-byte time can be converted into a string using OS_ConvertStandardDateAndTime or OS_ConvertDateAndTime.

Changing real-time

The real-time clock's time of day can be altered with OS_Word 15,8, its date with OS_Word 15,15, or both with OS_Word 15,24. These calls all use the time in a string format (see above).

Format field names

For most of the above calls the time string is passed or returned in a fixed, call-dependent format. However, for some calls you can customise the way that the time and date is presented by supplying a format string. The string is copied character for character to the output buffer unless a '%' is found. If this character is followed by any of the following codes - which may be in upper or lower case - then the appropriate value is copied to the output buffer:

Name Value Examples (UK)
CS Centiseconds 99
SE Seconds 59
MI Minutes 05
12 Hours in 12 hour format 07
24 Hours in 24 hour format 23
AM AM or PM indicator (in local language) PM
PM AM or PM indicator (in local language) AM
WE Weekday - full (in local language) Thursday
W3 Weekday - short (in local language) Thu
WN Weekday - number 5
DY Day of the month (in local language) 01
ST Ordinal pre/suffix (in local language) st nd rd th
MO Month name - full (in local language) September
M3 Month name - short (in local language) Sep
MN Month - number 09
CE Century 19
YR Year within century 87
WK Week of year (using local start of week) 52
DN Day of the year 364
TZ Timezone BST
0 Insert an ASCII 0 zero byte
% Insert a '%'

You must not make any assumptions about the nature or length of any fields that use the local language. For example: short forms of the weekday or month are three characters long in the UK territory, but may have a different length in other territories; the day of the month may not be numeric; ordinals may be null; and so on. However, you can find out the maximum length of fields for your territory by calling Territory_ReadCalendarInformation.

To cause leading zeros to be omitted, prefix the field with the letter 'Z'. For example, '%zmn' means the month number without leading zeros. '%0' may be used to split the output into several zero-terminated strings.

As an example, this format string:

%W3,%DY %M3 %CE%YR.%24:%MI:%SE

would produce this time string in the UK territory:

Tue,28 Mar 1989.13:25:54

OS_ConvertDateAndTime will convert a 5-byte time into a string using a supplied format string.

BCD conversions

The CMOS clock chip stores the time internally in a Binary Coded Decimal (BCD) format. OS_Word 14,1 will read the time as a 7-byte BCD block. OS_Word 14,2 will convert this BCD block into a string. These calls are provided for compatibility only, and you should not use them.

Timer events

There are three different causes of timer events: the interval timer, the timer chain and the VSync timer. You should not use these under the Wimp, as you cannot guarantee that your task will be paged in at the time of the event.

Interval timer

The interval timer is a 5-byte clock that increments every centisecond. If enabled by OS_Byte 14, an event will occur when the counter reaches zero. Thus to wait for a given time, the interval timer must be set to the negative of it using OS_Word 4. OS_Word 3 can read the current setting of the interval timer.

For example, to wait 10 seconds, -1000 must be passed to OS_Word 4.

The interval timer is kept for compatibility with earlier Acorn operating systems. Its use should be avoided if possible. It is especially important that this is not used under the Wimp, since it cannot cope with more than one program using it at once.

Timer chain

An easier to use and more sophisticated way for an application to be called at a given time is the timer chain. These are independent of event routines, but are used in a similar manner. OS_CallAfter can be used to get a given address to be called after a certain time has elapsed. OS_CallEvery is like this, but automatically reloads the counter when it has expired. OS_RemoveTickerEvent will cancel either OS_CallAfter before it occurs or OS_CallEvery to stop it repeating forever.

OS_CallAfter and OS_CallEvery are passed an address to call, the delay to wait and an identification word to return in R12. Thus, many timers can be running concurrently.

These are stored in a list which can be any size up to the machine memory limit.

Vertical sync timer

The screen is refreshed at a mode-dependent rate: typically from 50Hz (standard monitor type modes) to 70Hz or more (particularly with VGA or Super VGA monitor modes). From the time that the bottom of the screen is complete till the top of the screen commences again is a delay called the Vertical sync period. This allows the electron beam to go to this start position. The Vertical sync event coincides with the vertical sync beginning. You can use OS_Byte 14 to enable this event, so that flicker-free re-drawing can be done while the VDU is not being written to.

OS_Byte 176 provides access to a one byte counter that decrements at the rate of the Vertical sync event. Because the rate of this timer varies, you should not use it for running timing loops for games, music, etc.

Obsolete timers

OS_Byte 243 reads a temporary location used by the timer software. It is kept for compatibility with earlier Acorn operating systems and must not be used.

SWI Calls


OS_Byte 176
(SWI &06)

Read/write 50Hz counter

On entry

R0 = 176
R1 = 0 to read or new value to write
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call reads or writes a one-byte counter which is decremented at the rate of the Vertical sync interrupt. This rate is mode and monitor dependent, typically in the range 50 - 70Hz, Consequently you should not use this timer for precise timing loops.

Related SWIs

None

Related vectors

ByteV


OS_Byte 243
(SWI &06)

Read timer switch state

On entry

R0 = 243
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = switch state
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

In order to protect the centisecond clock against corruption during reset, the OS keeps two copies. One of them is the one which will be read or written when one of the OS_Words is called, the other is the one which will be updated during the next 100Hz interrupt. When the update has been performed correctly, the values are swapped. This OS_Byte enables you to read the byte which indicates which copy is being used. Its only practical use is as a location which changes 100 times a second.

This call is obsolete and should not be used.

Related SWIs

OS_Word 3, OS_Word 4

Related vectors

ByteV


OS_Word 1
(SWI &07)

Read system clock

On entry

R0 = 1
R1 = pointer to five byte block

On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On exit, the parameter block contains the value of the system clock at the instant of the call.

R1+0 = time (least significant byte)
R1+1 = ...
R1+2 = ...
R1+3 = ...
R1+4 = time (most significant byte)

The clock is incremented every centisecond. The value of the clock is preserved over a soft break and set to zero after a hard break.

Related SWIs

OS_Word 2

Related vectors

WordV


OS_Word 2
(SWI &07)

Write system clock

On entry

R0 = 2
R1 = pointer to five byte block with centisecond clock value in it

On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On entry, the parameter block contains the value to set the system clock.

R1+0 = time (least significant byte)
R1+1 = ...
R1+2 = ...
R1+3 = ...
R1+4 = time (most significant byte)

This allows the clock to be set to a specified value.

Related SWIs

OS_Word 1

Related vectors

WordV


OS_Word 3
(SWI &07)

Read interval timer

On entry

R0 = 3
R1 = pointer to five byte block

On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On exit, the parameter block contains the value of the interval timer at the instant of the call.

R1+0 = time (least significant byte)
R1+1 = ...
R1+2 = ...
R1+3 = ...
R1+4 = time (most significant byte)
Related SWIs

OS_Word 4

Related vectors

WordV


OS_Word 4
(SWI &07)

Write interval timer

On entry

R0 = 4
R1 = pointer to five byte block

On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On entry, the parameter block contains the value to set the interval timer.

R1+0 = time (least significant byte)
R1+1 = ...
R1+2 = ...
R1+3 = ...
R1+4 = time (most significant byte)

This call resets the interval timer to a specified value.

Like the system clock, the interval timer is incremented 100 times a second. The interval timer can be made to cause an event when its value reaches zero. To do this, it must be set to minus the number of centiseconds that are to elapse before the event takes place.

To produce repeated events, the routine servicing the timer event should reload the timer with the appropriate number. For example, to produce an event every 10 seconds, reload it with -1000 (&FFFFFFFC18). An alternative is to use the special ticker event, described in the Events.

Note that you must use OS_Byte 14 to enable the interval timer event.

Related SWIs

OS_Word 3

Related vectors

WordV


OS_Word 14,0
(SWI &07)

Read soft copy of the real-time clock as a string, converting to local time

On entry

R0 = 14
R1 = pointer to parameter block

R1+0 = 0 (reason code)
On exit

R0, R1 preserved

Interrupts

Interrupts are enabled (in RISC OS 2, the interrupt status is not altered)
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On exit, the parameter block contains the local time as a string terminated by a Return character (ASCII 13). The format of the string depends on the territory which the computer is set to use. (It is fixed in RISC OS 2, which does not support territories.)

This time string comes from the soft copy of the real-time clock maintained by RISC OS, rather than from the CMOS clock chip itself.

This call is equivalent to the *Time command.

Related SWIs

OS_Word 15

Related vectors

WordV


OS_Word 14,1
(SWI &07)

Read time in Binary Coded Decimal (BCD) format, converting to local time

On entry

R0 = 14
R1 = pointer to parameter block

R1+0 = 1 (reason code)
On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On exit, the parameter block contains a seven-byte BCD clock value:

R1 + 0 = year (00 - 99)
R1 + 1 = month (01 - 12; 01 = January etc)
R1 + 2 = day of month (01 - 31)
R1 + 3 = day of week (01 - 07; 01 = Sunday etc)
R1 + 4 = hours (00 - 23)
R1 + 5 = minutes (00 - 59)
R1 + 6 = seconds (00 - 59)

Under RISC OS 2 the clock value is read directly from the CMOS real time clock chip, which is assumed to be set to local time, and so the value is not further converted. Under later versions of RISC OS the clock is read from a soft copy of the real time, which is assumed to be set to UTC, and so the value is then converted to local time.

Related SWIs

OS_Word 15

Related vectors

WordV


OS_Word 14,2
(SWI &07)

Convert BCD clock value into string format

On entry

R0 = 14
R1 = pointer to parameter block

R1 + 0 = 2 reason code
R1 + 1 = year (00 - 99)
R1 + 2 = month (01 - 12; 01 = January etc)
R1 + 3 = day of month (01 - 31)
R1 + 4 = day of week (01 - 07; 01 = Sunday etc)
R1 + 5 = hours (00 - 23)
R1 + 6 = minutes (00 - 59)
R1 + 7 = seconds (00 - 59)
On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On entry, the parameter block contains a 7-byte BCD clock value:

On exit, the parameter block contains a string terminated by a Return character (ASCII 13), representing the same time. The format of the string depends on the territory which the computer is set to use. (It is fixed in RISC OS 2, which does not support territories.)

Related SWIs

OS_Word 15

Related vectors

WordV


OS_Word 14,3
(SWI &07)

Read real-time in 5-byte format

On entry

R0 = 14
R1 = pointer to parameter block

R1+0 = 3 (reason code)
On exit

R0 preserved
R1 preserved:

R1+0 = LSB of time
R1+1 = ...
R1+2 = ...
R1+3 = ...
R1+4 = MSB of time
Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

On exit the parameter block contains the 5-byte real time read directly from the soft copy of the real-time clock. This number gives the elapsed number of centiseconds since 00:00:00 on January 1 1900. Under RISC OS 2 the real-time clock is assumed to be set to local time; under later versions the real-time clock is assumed to be set to UTC.

This 5-byte real-time is used for time/date stamping by the filing system. It is also useful for utilities which are used for building consistent systems, eg 'Make'.

Related SWIs

OS_Word 15

Related vectors

WordV


OS_Word 15,8
(SWI &07)

Writes the time of day to both the CMOS clock and its soft copy

On entry

R0 = 15
R1 = pointer to parameter block

R1+0 = 8 (reason code)
R1+1... = string giving time of day (in local language)
On exit

R0, R1 preserved.

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call writes the time of day to both the CMOS clock and its soft copy.

On entry, the parameter block contains the local time of day as a string; the format this string must have depends on the territory which the computer is set to use. (It is fixed in RISC OS 2, which does not support territories.)

The format for the UK territory (and for RISC OS 2) is:

HH:MM:SS eg 17:35:04

Related SWIs

OS_Word 14

Related vectors

WordV


OS_Word 15,15
(SWI &07)

Writes the date to both the CMOS clock and its soft copy

On entry

R0 = 15
R1 = pointer to parameter block

R1+0 = 15 (reason code)
R1+1... = string giving date (in local language)
On exit

R0, R1 preserved

The C flag will be set on exit, if the parameter block contained a format error

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call writes the date to both the CMOS clock and its soft copy.

On entry, the parameter block contains the local date as a string; the format this string must have depends on the territory which the computer is set to use. (It is fixed in RISC OS 2, which does not support territories.)

The format for the UK territory (and for RISC OS 2) is:

Day,DD MMM YYYY eg Mon,17 Feb 1992

Related SWIs

OS_Word 14

Related vectors

WordV


OS_Word 15,24
(SWI &07)

Writes the time of day and date to both the CMOS clock and its soft copy

On entry

R0 = 15
R1 = pointer to parameter block

R1+0 = 24 (reason code)
R1+1... = string giving time of day and date (in local language)
On exit

R0, R1 preserved

The C flag will be set on exit, if the parameter block contained a format error.

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call writes the time of day and date to both the CMOS clock and its soft copy.

On entry, the parameter block contains the local time of day and date as a string; the format this string must have depends on the territory which the computer is set to use. (It is fixed in RISC OS 2, which does not support territories.)

The format for the UK territory (and for RISC OS 2) is:

Day,DD MMMYYYY.HH:MM:SS eg Mon,17 Feb 1992.17:35:04

Related SWIs

OS_Word 14

Related vectors

WordV


OS_CallAfter
(SWI &3B)

Call a specified address after a delay

On entry

R0 = time in centiseconds
R1 = address to call
R2 = value of R12 to call code with

On exit

R0 - R2 preserved

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

OS_CallAfter calls the code pointed to by R1 after the delay specified in R0. The code is called in SVC mode with interrupts disabled. It must preserve all registers, and return using the instruction MOV R15, R14.

OS_RemoveTickerEvent can be used to cancel a pending OS_CallAfter

In RISC OS 2 this call may return incorrect error pointers. An invalid value of R0 now generates the error message 'Invalid time interval', rather than the null string generated by RISC OS 2.

Related SWIs

OS_CallEvery, OS_RemoveTickerEvent

Related vectors

None


OS_CallEvery
(SWI &3C)

Call a specified address every time a delay elapses

On entry

R0 = (delay in centiseconds) - 1
R1 = address to call
R2 = value of R12 to call code with

On exit

R0 - R2 preserved

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

OS_CallEvery calls the code pointed to by R1 every (R0+1) centiseconds, until OS_RemoveTickerEvent is executed or Break is pressed. The code is called in SVC mode with interrupts disabled. It must preserve all registers, and return using the instruction MOV R15, R14.

The minimum value for R0 is 1, which means the minimum possible delay is 2 centiseconds. If you wish to be called every centisecond, you must instead claim TickerV.

In RISC OS 2 this call may return incorrect error pointers. An invalid value of R0 now generates the error message 'Invalid time interval', rather than the null string generated by RISC OS 2.

Related SWIs

OS_CallAfter, OS_RemoveTickerEvent

Related vectors

None


OS_RemoveTickerEvent
(SWI &3D)

Remove a given call address and R12 value from the ticker event list

On entry

R0 = call address
R1 = value of R12 used in OS_CallEvery or OS_CallAfter

On exit

R0, R1 preserved

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

OS_RemoveTickerEvent takes R0 as the address and R1 as the R12 value of the event to find and remove from its list.

It is used to stop an event set up by a call to OS_CallAfter or OS_CallEvery. The parameters passed must match those originally passed to OS_CallEvery or OS_CallAfter for it to remove the correct event.

Note: You cannot use this call to remove a ticker event from within that event's own code. Instead, your ticker event must call OS_AddCallBack to add a transient CallBack that makes the call to OS_RemoveTickerEvent.

Related SWIs

OS_CallAfter, OS_CallEvery

Related vectors

None


OS_ReadMonotonicTime
(SWI &42)

Number of centiseconds since the last hard reset

On entry

--

On exit

R0 = time in centiseconds

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

OS_ReadMonotonicTime returns the number of centiseconds since the last hard reset, or switching on of the machine. 'Monotonic' refers to the fact that this timer is guaranteed to change with time (increasing until it wraps around). It is used, for example, to time-stamp mouse events.

Related SWIs

None

Related vectors

None


OS_ConvertStandardDateAndTime
(SWI &C0)

Converts a 5-byte time into a string

On entry

R0 = pointer to 5-byte time block
R1 = pointer to buffer for resulting string
R2 = size of buffer

On exit

R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating zero in buffer
R2 = number of free bytes in buffer

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

OS_ConvertStandardDateAndTime converts a five-byte value representing the number of centiseconds since 00:00:00 on January 1st 1900 into a string. It converts it using a standard format string stored in the system variable 'Sys$DateFormat' and places it in a buffer (which should be at least 20 bytes).

For details of the format field names see the chapter entitled Format field names.

From RISC OS 3 onwards this SWI simply calls Territory_ConvertStandardDateAndTime, which you should use instead.

Related SWIs

OS_ConvertDateAndTime, Territory_ConvertStandardDateAndTime

Related vectors

None


OS_ConvertDateAndTime
(SWI &C1)

Convert 5-byte time into a string using a supplied format string

On entry

R0 = pointer to 5-byte time block
R1 = pointer to buffer for resulting string
R2 = size of buffer
R3 = pointer to format string (null terminated)

On exit

R0 = pointer to buffer (R1 on entry)
R1 = pointer to terminating zero in buffer
R2 = number of free bytes in buffer
R3 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

OS_ConvertDateAndTime converts a five byte value representing the number of centiseconds since 00:00:00 on January 1st 1900 into a string. It converts it using the format string supplied.

Apart from the following exception, the format string is copied directly into the result buffer. However, whenever '%' appears in the format string, the next one or two characters are treated as a special field name which is replaced by a component of the current time.

For details of the format field names see the chapter entitled Format field names.

From RISC OS 3 onwards this SWI simply calls Territory_ConvertDateAndTime, which you should use instead.

Related SWIs

OS_ConvertStandardDateAndTime, Territory_ConvertDateAndTime

Related vectors

None

*Commands


*Time

Displays the day, date and time of day

Syntax
*Time
Parameters

None

Use

*Time displays the day, date and time of day. It is displayed in the same format as OS_Word 14,0.

Example
*Time
Related commands

None

Related SWIs

OS_Word 14,0, OS_Word 15, OS_ConvertStandardDateAndTime,
OS_ConvertDateAndTime, Territory_ConvertDateAndTime, Territory_ConvertStandardDateAndTime

Related vectors

WordV, WrchV

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015