This document covers various aspects concerning the handling of store clock values in Natural applications.
The following topics are covered:
The Natural system variable *TIMESTMP provides the (mainframe) machine-internal store
clock value (STCK). The store clock is an 8-byte binary field. It counts the microseconds
since 1900-01-01 00:00:00 (UTC) whereby bit position 51 represents exactly one microsecond
(bit position 0 is the leftmost bit). The remaining 12 bits can contain
higher precision values such as nanoseconds or a processor ID, depending on the machine
implementation.
The store clock will reach its highest possible value on 2042-09-17 23:53:47.370495 (UTC)
at which time all 52 bits will be set to 1. Afterwards, the store clock will
restart counting from 0. The date on which the clock is reset is referred to
below as wrap-date.
After the wrap-date, the store clock will use the same values as in the range from 1900 to 2042. Therefore, it cannot be determined whether a store clock has been taken before or after the wrap-date.
If the store clock covers the years from 1900 to 2042, we call it the original store clock.
The year 2042 issue leads to the following impacts:
Compare and sort
Comparing time-related values should reflect the chronological sequence so that
previous values are smaller than later values. Unfortunately, a store clock value
taken just before the wrap-date is greater than a store clock value after that date
when the store clock was reset to 0. Thus, comparing such store clock
values will lead to incorrect results. For example, the store clock of 2040-01-01
(before the wrap-date) is greater than the store clock of 2043-01-01 (after the
wrap-date). If both the store clock values taken before and after the wrap-date are
used for sorting, they will not correspond to the chronological sequence.
Conversion
If a store clock value is converted into a date, it is assumed that it was taken in
the years from 1900 to 2042. If the store clock has actually been taken after the
wrap-date, the conversion will therefore lead to an incorrect result. For example, a
store clock value was taken on 2043-12-07 (after wrap-date). If this store clock is
converted into a date, it will result in 1901-03-21.
Calculation of a time difference
If store clock values are converted into microseconds, they can be used to calculate
a time difference. This works fine if the wrap-date is not involved. Subtracting a
(big) store clock value taken before the wrap-date from a (small) store clock value
taken after the wrap-date will result in an invalid (big negative) result. For
example, the calculation of the store clock time difference between the years 2039 and
2043, will result in “-138 years”.
To overcome the year 2042 issue, there are two approaches:
General approach: Extended Store Clock
Temporary approach: Store Clock with Sliding Window
For both approaches, Software AG provides application programming interfaces (APIs) in the system library SYSEXT as described in the section Natural APIs for Store Clock Processing.
The Natural system variable *TIMESTMPX provides the (mainframe) machine-internal extended
store clock value (STCKE). The extended store clock is a 16-byte binary field. It counts
the microseconds since 1900-01-01 00:00:00 (UTC) whereby bit position 59 represents
exactly one microsecond (bit position 0 is the very left bit). The original
store clock time representation is retained at byte 2-9. An extra overflow byte is added
to the left, the so-called epoch index.
The extended store clock covers the years from 1900 to 38434.
Compared with the original store clock, the extended store clock provides the following improvements:
Compare and sort
The extended store clock always delivers the expected chronological sequence when you
compare or sort values.
Conversion
Natural APIs can be used to convert extended store clock values. Because every
extended store clock value in the extended store clock range is unique, the
interpretation is always correct.
Calculation of a time difference
Natural APIs can be used to convert extended store clock values into microseconds
(since 1900-01-01). A difference calculation with these values provides the correct
time duration.
Outlook
No further code change is required in the future.
Before migrating from original store clock to extended store clock, consider the following:
The size of the binary field increases from 8 bytes to 16 bytes. If your application needs only the microsecond time information, you can simply use the first 8 bytes of the extended store clock value. But keep in mind that the value still contains the extended store clock format with the epoch index at the left. Before you can process it with a Natural API, you must expand it to 16 bytes again.
It is not possible to compare an extended store clock value directly against an original store clock value (nor against a Store Clock with Sliding Window). The extended store clock starts with the epoch index and a comparison will not return a correct result.
Saved store clock values must be converted into extended store clock values. You may
use the copycode USR9201R for this task.
Every program which processes store clock values must be adjusted.
This complete conversion implies major changes.
If a store clock value is converted into a date, the original store clock conversion assumes that it was taken in the range from 1900 to 2042. To extend the range, we use a sliding window which supports the range from 1971 to 2114. This implies that the years from 1900 to 1971 are no longer supported.
In the year 1971 the first bit in the store clock value switches to 1.
Therefore, this bit is used for the realization of the sliding window:
From 1971 to 2042 the first bit is 1. Store clock values of this range
are interpreted as before.
From 1900 to 1971 and from 2042 to 2114, the first bit is 0. With the
sliding window these store clock values are interpreted as 2042 – 2114.
When a store clock with sliding window is converted into microseconds and the first bit
is 0, the binary store clock value is extended at the left with
x’01’ before the conversion, so that the result always reflects the number
of microseconds since 1900-01-01.
The range of the store clock with sliding window
starts at 1971-05-11 11:56:53.685248 (UTC) and
ends at 2114-01-26 11:50:41.055743 (UTC).
Note:
If you sort 8-byte store clock values, they will not be in the chronological sequence even if you use the sliding window. For this task you must use extended store clock values.
If you compare 8-byte store clock values, the result will not reflect the
chronological sequence even if you use the sliding window. You can use the copycode
USR9201D for this task.
If a store clock is taken after the end date of the sliding window, it will be wrongly interpreted. In this case you must also use extended store clock values.
A store clock value is saved in an 8-byte field in which the last 12 bits are never zero. This fact can be used to determine whether the field for the store clock is still unused. If all 8 bytes in the field are zero (“NULL value”), the field is still unused, and a store clock value was not yet saved. You must ensure that the store clock field does not contain a NULL value before using it in a conversion function.
Compared with the original store clock, the store clock with sliding window provides the following improvements:
Conversion
Natural APIs can be used to convert store clock values with sliding window correctly
if store clock values have been taken from 1971 to 2114.
Calculation of a time difference
Natural APIs can be used to convert store clock values with sliding window into
microseconds (since 1900-01-01). A difference calculation with these values provides
the correct time duration (if the store clock values are from 1971 to 2114).
Outlook
Year 2042 issue is postponed until 2114.
Compared with the extended store clock, the store clock with sliding window provides the following temporary advantages:
Size
The size of the store clock value remains at 8 bytes.
Data conversion
There is no need to migrate the store clock data to 16-byte values. Saved 8-byte
store clock data will be interpreted correctly if it is in the range 1971-2114.
Program modifications
The conversion implies minor changes. The system variable *TIMESTMP can be used
further on.
Before migrating original store clock to store clock with sliding window, consider the following:
The migration must be done before 2042.
Further code changes will be required before the end of the sliding window in 2114.
If your application calls a Natural API which supports the original store clock value, replace it by an API which supports the store clock value with sliding window.
If you compare or sort binary store clock values, they will not be in the chronological sequence. See the note above.
The Natural system variable *TIMX provides the local time in tenth of seconds. If the
local time is required in a higher precision, the Natural API USR9178N can be
used. It provides the local time and the corresponding UTC time in store clock format
(B8), in microseconds since 1900-01-01 and in the Natural time (T) format. Additionally,
it provides the time differential, a standard DATETIME value and the time
zone. Functions are available to convert the values into other formats. The copycodes
USR9178X, USR9178Y and USR9178Z provide mainly
the same functionality as the subprogram USR9178N with an essentially better
performance.
The first 7 bytes in the local store clock value have the same content as the original
store clock whereby bit positions 0 – 51 contain the microseconds of the local time.
Therefore, standard APIs (like USR1023* or USR9201*) can be used
for the interpretation of a local store clock value.
The last byte of a local store clock value generated by USR9178*, contains
the time differential. With this information it can later be determined in which time zone
the local store clock was taken, especially whether it has been taken in the DST (daylight
saving time).
The time differential reflects the following difference:
Time differential = Local time - UTC time |
The API USR9178N and the corresponding copycodes provide the time
differential in units of 1/10 seconds.
The last byte of a local store clock value contains the time differential in units of 15 min as signed integer (format I1).
The API USR9178N also returns the time zone related to the time
differential:
-hh:ii for a negative time differential, or
+hh:ii otherwise.
DATETIMEThe API USR9178N returns the standard DATETIME value:
yyyy-mm-ddThh:ii:ss.fff
where fff is the time fraction in milliseconds.
The following Natural Application Programming Interfaces (APIs) for processing of store clock values are provided in the Natural library SYSEXT:
|
Natural API
|
Function
|
Store Clock
|
Previous Version
|
||
|
Original
|
Sliding Window
|
Extended
|
|||
| USR1009N | Convert store clock with sliding window into microseconds | Yes | Yes | No | |
| USR1023N | Convert time-related variables | Yes | No | No | |
| USR9178N | Maintain local store clock value | No | Yes | No | |
| USR9201N | Convert time-related variables | No | Yes | Yes | USR1023N |
The API converts a store clock value into microseconds since 1900-01-01. The store clock value is interpreted by default without sliding window (range 1900-2042). An optional parameter is available to interpret the store clock value with the sliding window (range 1971-2114).
It is recommended to use the copycode USR9201Y (with sliding window) or
USR1023Y (without sliding window) instead of the API USR1009N
for better performance.
The API converts a time-related variable into other formats. The API uses the original store clock (1900 – 2042).
It is strongly recommended to use the API USR9201N instead of
USR1023N. Otherwise, store clock values will be incorrectly interpreted
after the year 2042. If you take, for example, a store clock on 2043-12-07, the API
USR1023N will interpret it as 1901-03-21.
The API USR1023N expects one of the following formats as input:
Natural date and time,
Natural date,
microseconds (since 1900-01-01), or
original store clock,
and converts it into all other formats.
Additional to the API, the following copycodes are provided:
USR1023W - Convert microseconds into original store clock
USR1023X - Convert microseconds into Natural time
USR1023Y - Convert original store clock into microseconds
USR1023Z - Convert Natural time into microseconds
The copycodes are essentially faster than the subprogram USR1023N.
The API maintains local store clock values. It supports store clock with sliding window (1971 - 2114).
For function “C”, it returns the current values of:
Local store clock
UTC store clock
Time differential in 1/10 seconds
Local time in microseconds
UTC time in microseconds
Local time in Natural (T) format
UTC time in Natural (T) format
Standard DATETIME
Time zone
For function “L”, it converts a local store clock value into the other formats.
For function “U”, it converts a UTC store clock value and a time differential into the other formats.
Additional to the API, the following copycodes are provided:
USR9178X - Get current local store clock, UTC store clock and time differential.
USR9178Y - Convert local store clock into UTC store clock and time differential.
USR9178Z - Convert UTC store clock and time differential into local store clock.
The API is the successor of USR1023N. It supports store clock with sliding
window (1971 - 2114) and extended store clock (1900 - 38434).
The API expects one of the following formats as input:
Natural date and time,
Natural time,
Natural date,
microseconds (since 1900-01-01),
store clock with sliding window, or
extended store clock,
and converts it into all other formats.
Additional to the API, the following copycodes are provided:
USR9201R - Convert store clock with sliding window into extended store
clock
USR9201S - Convert extended store clock into store clock with sliding
window
USR9201U - Convert microseconds into extended store clock
USR9201V - Convert extended store clock into microseconds
USR9201W - Convert microseconds into store clock with sliding window
USR9201X - Convert microseconds into Natural time
USR9201Y - Convert store clock with sliding window into microseconds
USR9201Z - Convert Natural time into microseconds
USR9201D - Calculate time difference of two store clock values with
sliding window
Note:
The copycode USR9201D can also be used to compare two store clock values
which have been taken in the sliding window range (1971-2114).
The copycodes are essentially faster than the subprogram USR9201N.
A test for 10,000 conversions shows that:
the subprogram USR9201N requires about 35 ms, and
the copycode USR9201Y requires about 5 ms.