Guardian Procedure Calls Reference Manual (G06.25+)

Guardian Procedure Calls (C)
Guardian Procedure Calls Reference Manual—522629-013
3-150
CONVERTTIMESTAMP Procedure
It is vital to add at least one period of nonzero DST offset to the DST table, to avoid
CONVERTTIMESTAMP reporting error 2 (DST table not loaded).
In addition to the accurate table entries recommended above, it is good practice to
add fictitious entries to the DST table, to avoid CONVERTTIMESTAMP reporting
error 1 (DST range error) when it converts times earlier than expected or later than
expected. It is good practice to add a fictitious entry for a time far in the past and a
fictitious or speculative entry for a time far in the future. For example, you might
add DST table entries for the year 1000 and for the year 3999.
To add entries to the DST table, use the following procedures:
•
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.
D-series releases, or G04.00
and earlier G-series releases
ADDDSTTRANSITION procedure or the
ADDDSTTRANSITION TACL command
G05.00 and later G-series
releases
ADDDSTTRANSITION procedure,
ADDDSTTRANSITION TACL command, or
the DST_TRANSITION_ADD_ procedure