Guardian Procedure Calls Reference Manual

• Use (or Avoidance) of Local Civil Time
It is hard to avoid all problems with conversion between local civil time (which includes the
effect of daylight saving time) and GMT or local standard time.
Because civil time is convenient for people to use for comparison with local clocks, some use
of civil time is expected. Accordingly, the best strategy might be to store all timestamps in
GMT, and then to convert the GMT timestamps to civil time, when desired, before displaying
them. It might also be helpful to display the GMT timestamp. This would allow people to clarify
cases such as timestamps near a DST transition or timestamps that might have been generated
on a different system, possibly in a different time zone.
If a program restricts itself to converting from GMT to LCT at the local system, and never
converts in the opposite direction or at a remote node, then the errors that might unexpectedly
occur are error 1 (DST range error) or 2 (DST table not loaded). In both of these cases, the
conversion from GMT to LCT will assume a DST offset of 0. If daylight saving time is not in
effect for the time in question then the timestamp will be correct. Otherwise, it will be incorrect
by the DST offset, which is typically one hour.
When converting from GMT to LCT at the local system, it is best to use the value returned from
CONVERTTIMESTAMP without checking the error parameter. In rare cases, such as when
comparing timestamps to decide whether to rebuild a file, it might be better to take some
special action as a safety precaution, such as adding or subtracting one hour from the
timestamp.
• Error Handling
Whenever a program uses CONVERTTIMESTAMP to convert to or from civil time, there is a
possibility that CONVERTTIMESTAMP will report a nonzero value of error. It is very undesirable
for the program to take any extreme action such as abending or failing a transaction because
of a such a conversion error.
It is particularly important to avoid abending or other extreme actions when responding to
errors in time conversions that might be several years in the past or the future. It is difficult for
operators of a computer system to provide accurate information about future and past daylight
saving time data.
Example
#include <cextdecs (CONVERTTIMESTAMP)>
#include <ktdmtyp.h> /* define long long etc. */
long long gmt_time; /* original (GMT) time stamp */
long long display_time; /* displayable (Local Civil Time) time stamp */
display_time=CONVERTTIMESTAMP( gmt_time, 0 ); /* GMT to LCT */
Related Programming Manual
For programming information about the CONVERTTIMESTAMP procedure, see the Guardian
Programmer's Guide.
224 Guardian Procedure Calls (C)