TODClock (System function)

From m204wiki
Jump to navigation Jump to search

Get binary TOD clock value (System class)

[Introduced in Model 204 7.5]

This method provides access to the value of the hardware TOD (Time Of Day) clock.


%string = %(System):TODClock

Syntax terms

%stringThe eight-byte binary value of the TOD clock at the time the method was invoked.
%(System) The class name in parentheses denotes a shared method. TODClock can also be invoked via a System object variable, which may be Null.

Usage notes

  • Bit 51 of the TOD clock (where the highest order bit is bit 0 and the lowest is bit 63) is incremented by one every microsecond. Bit 31 is incremented approximately once every second. For more information on the TOD clock see the z/Architecture Principles of Operation.
  • The TOD clock has 64 bits of precision which requires approximately 20 significant decimal digits. Unfortunately Model 204 only really supports 15 decimal places. As such, the TOD clock value is more useful as a simple stamp than as a value used in calculations. However, with a bit of effort, it can be used to get more precise timings than is possible otherwise with Model 204. See the example below for an illustration.


The following local method indicates how TOD clock values can be used to provide a microsecond precision interval calculator. The inputs (method object and parameter) are assumed to be the results of TODClock calls.

local function (string):microsecondTodClockDifference(%start is string len 8) is float assert %this:length eq 8 assert %start:length eq 8 %highWord is float %lowWord is float %hexValue1 is string len 16 %hexValue2 is string len 16 %hexValue2 = %this:stringToHex %hexValue1 = %start:stringToHex %highWord = %hexValue2:left(8):hexToInteger - %hexValue1:left(8):hexToInteger %lowWord = %hexValue2:substring(9, 5):hexToInteger - %hexValue1:substring(9, 5):hexToInteger return %highWord * 2:toPower(32 - 12) + %lowWord end function

While in general TOD clock values or microseconds since January 1, 1900 (the standard time base in 204) require more significant digits than 204 provides, microsecond intervals can be easily handled by Model 204 unless the intervals exceed several years. With the above code, one can do microsecond level interval timing:

%tod1 is string len 8 %tod2 is string len 8 %tod1 = %(system):todclock pause 1 %tod2 = %(system):todclock printText {~=%tod1:stringToHex}, {~=%tod2:stringToHex} printText {~=%tod2:microsecondTodClockDifference(%tod1)}

One would expect the value printed by the last line to be just a little bit more than 1000000 (microseconds).

See also