Prototype and description of the function gettzcurrentbynum()

(Function of the unlock requiring group "Time Zone Calculations")

 

gettzcurrentbynum()
Determination of the current time zone parameters from a GeoDLL time zone index.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettzcurrentbynum(
     unsigned short nTimeZone,
     float *fUtc,
     float *fDst,
     unsigned long *lIsDstActiv,
     unsigned long *nDstStart,
     unsigned long *nDstEnd,
     unsigned long *lIsSouthHemi,
     float *fLocalTime);

Prototype of the DLL function in Visual Objects syntax:
_DLL function gettzcurrentbynum(;
     nTimeZone as word,;                     // 2 Byte
     fUtc ref real4,;                        // 4 Byte
     fDst ref real4,;                        // 4 Byte
     lIsDstActiv ref logic,;                 // 4 Byte
     dwDstStart ref dword,;                  // 4 Byte
     dwDstEnd ref dword,;                    // 4 Byte
     lIsSouthHemi ref logic,;                // 4 Byte
     fLocalTime ref real4);                  // 4 Byte
as logic pascal:geodll32.gettzcurrentbynum   // 4 Byte


A time zone is a region that has an uniform standard time for legal, commercial,
and social purposes. Time zones are primarily longitude dependent, but secondary
they follow the boundaries of countries or their administrative subdivisions.
The time zones supported by GeoDLL are based on an uniform naming convention,
designed by Paul Eggert, such as America/New_York and Europe/Paris. The time
zones have offsets from Coordinated Universal Time (UTC) as a number of hours
(UTC-12 to UTC+12). Many higher latitude countries use Daylight Saving Time
(DST) for a part of the year, typically by changing clocks one hour forward.

The function determined from a GeoDLL time zone index the current time zone
parameters UTC, DST and local time, as well as the dates for the beginning and
end of the daylight saving period (DST period). Flags indicate whether a DST
period in the time zone is used and whether the DST period, as usual in the
southern hemisphere, exceeds the turn of the year. For the calculations the
function takes the current date from the computer.

The local time fLocalTime is composed of the UTC and DST, but the DST is only
added if the current date is within the DST period.

The beginning and the end of the DST period will be returned in the parameters
dwDstStart and dwDstEnd given as a date of the current year with the following
syntax:
jjjjmmtt
  jjjj four digits indicating the current year
  mm   two digits indicating the month in which the DST period changes
  tt   two digits indicating the day on which the DST period changes

If dwDstStart for the start of DST period contains a higher date than
dwDstEnd for the end of the DST period, the time zone is located in the
southern hemisphere. In this case the DST period exceeds the turn of the year.

If no DST period is used in the time zone, the parameters pszDstStart, pszDstEnd
and fDst contain the value 0 and the parameters lIsDstActiv and lIsSouthHemi
are set to FALSE.

The required GeoDLL time zone index can be determined like follows:
gettznumbycoordexact()  Exact determination of a index from a coordinate
gettznumbycoordfast()   Fast determination of a index from a coordinate
List                    From the list of supported GeoDLL time zones


The parameters are passed and/or returned as follows:
nTimeZone    Time zone index, which has been previously calculated by other time
             zone functions or has been read from the list.

fUtc         Offset of the time zone from the Coordinated Universal Time (UTC)
(ref)        in hours. The value is returned by reference.

fDst         DST in hours, if Daylight Saving Time is used in the time zone. The
(ref)        value is returned by reference.
0.0:         If no Daylight Saving Time is used in the time zone.

lIsDstActiv  Flag for the activity of the DST at the current date. The flag is
(ref)        returned by reference.
TRUE:        Current date is within the DST period.
FALSE:       Current date is outside the DST period or DST is not used in the
             time zone.

dwDstStart   Date on which the DST period starts. The value is returned by
(ref)        reference. Syntax see above.

dwDstEnd     Date on which the DST period ends. The value is returned by
(ref)        reference. Syntax see above.

lIsSouthHemi Flag for the location of the time zone in the southern hemisphere.
(ref)        The flag is returned by reference.
TRUE:        dwDstStart › dwDstEnd --› southern hemisphere
FALSE:       dwDstStart ‹ dwDstEnd --› nothern hemisphere

fLocalTime   Local time in the time zone considering the DST period at the
(ref)        current date as an offset from Coordinated Universal Time (UTC) in
             hours. The value is returned by reference.
             fLocalTime = fUtc + fDst

returnVal    In case of an error the function returns FALSE, otherwise TRUE.


Unlocking:
This function is a component of the unlock requiring function group
"Time zone calculations". It is unlocked for unrestricted use together with the
other functions of the group by passing the unlock parameters, acquired
from the software distribution company, trough the function setunlockcode().
Without unlocking only a few function calls for test purposes (shareware
principle) are possible.