TZ

[Simon Bowring]

>OK, here's a question. As I understand it, most OS/2 programs are not
>allowed to access the hardware directly, right? So none of these apps
>are directly querying the RTC are they? There must be *some* low
>level service provided by the OS/2 kernel or something that is
>actually querying the RTC, no?

Yes, you're correct, there are time related functions in the OS/2
APIs, but they do not really support timezones.

To explain, I am going to have to go into a level of detail that I would
prefer not to, but here goes...

DosGetDateTime() and DosSetDateTime() are the natice OS/2 date'n'time
APIs.  They just allow you to get or set "the time and date".  They do 
also support a timezone field (minutes different from UTC), but not
in a useful fashion (changing the timezone, does not affect the values
returned for the time, it simply records the offset for you), and this 
has nothing to do with the C language's TZ environment variable.

Then there are the standard ANSI C time related functions, these work
in terms of UTC. "All" C/C++ programmers use these functions and if
used correctly, all such code is portable across all ANSI C 
implementations, so an OS/2, DOS, Linux, AIX or MVS program can use 
exactly the same code and will behave identically (despite the fact that 
some machines use UTC and some use local time natively).

So, the C functions all work in terms of UTC; some of the more significant 
funcs are:

	time()	returns the number of elapsed seconds since 
                00:00:00 Jan 01 1970 *UTC*.

	        The values retured from this function are of type
                time_t which is the "native unix" and "native C" way of
                handling time'n'dates.  The nice thing about these time_t
                values is that they are a simple scalar way of representing 
                times, so that you can simply manipulate and compare them
                without having to worry about the considerable complexities 
                involved with time like how many days there are in a month or 
                whether it is a leap year etc. e.g. you can add and take away 
                from them, so to calculate the time'n'date 4 weeks from "now" 
                you could:

                    four_weeks_ahead = time(NULL) + 4*7*24*60*60;
                
                You can also easily compare times "if (time_1 > time 2)" etc.

	mktime() Takes a "structured time" and converts it to a time_t.
                 The structured time is composed of:
		     seconds after the minute -- [0,61]  
		     minutes after the hour   -- [0,59]  
                     hours after midnight     -- [0,23]  
                     day of the month         -- [1,31]  
                     months since January     -- [0,11]  
                     years since 1900                    
                     days since Sunday        -- [0,6]   
                     days since January 1     -- [0,365] 
                     is_dst Daylight Savings Time flag -- TRUE/FALSE

	localtime()  Takes a (UTC) time_t and converts it to a "structured 
                     time" according to the local time zone (typically 
                     derived from TZ).

A traditional unix implementation of time() will therefore simply return 
the time according to the hardware's real-time clock (running in UTC), 
it's implemetation of localtime(), must however read the TZ variable and 
(potentially) make some adjustments.

Under OS/2, to be ANSI C conformant, time() must also inspect the TZ 
variable,  and use it to convert the local time returned by 
DosGetDatTime() to UTC.

Also under OS/2, localtime() should be identical to the unix version, 
and must also inspect the TZ variable, and use it to convert the UTC 
time returned by time() to local time.

The trouble is the OS/2 operating system can only know about calls to 
DosGetDateTime(), it cannot know whether these are native calls called 
directly by the programmer, or whether they have originated from some 
vendors C RTL time() function (and many programs will do both).  Since 
the operating system has no way of knowing if the program is going to 
apply an adjustment to the value returned [via a call to localtime()], 
how can it apply the adjustment "in advance".  It's important to realise 
that within the same program many calls to time() will *not*  be followed
by calls to localtime(), but some will, this is because (in C/Unix) you 
manipulate all times as UTC, and only convert to and from localtime ONLY
upon input or ouput (to/from the user).
 
Basically your not going to know which time a progarmmer wanted at the 
point that DosGetDateTime() is called (it may be UTC or local, because 
he may be going to adjust it later and the same program is normally
going to exhibit both behaviours.

I hope this makes sense - apologies to all those bored of this thread,
but then you won't have read this far!

Simon