Prototype and description of the function gettznumbycoordfast()

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

 

gettznumbycoordfast()
Fast determination of a GeoDLL time zone index from a coordinate.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettznumbycoordfast(
     double fLongitude,
     double fLatitude,
     unsigned short nTzType,
     unsigned short *nTimeZone);

Prototype of the DLL function in Visual Objects syntax:
_DLL function gettznumbycoordfast(;
     fLongitude as real8,;                     // 8 Byte
     fLatitude as real8,;                      // 8 Byte
     nTzType as word,;                         // 2 Byte
     nTimeZone ref word);                      // 4 Byte
as logic pascal:geodll32.gettznumbycoordfast   // 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 calculates alternatively Time Zones including the Territorial Sea
Baseline and the Twelve Mile Territorial Limit. To include the Three Mile
Territorial Limit, the 24-Mile Contiguous Zone or the 200-Mile Exclusive
Economic Zone, the function gettznumbycoordexact() must be used.

The function determines a GeoDLL time zone index of a time zone from a
geographic coordinate in WGS84 datum (fLongitude, fLatitude). In comparison
with the function gettznumbycoordexact(), the function gettznumbycoordfast() is
considerable faster, but it determines the time zone in the border areas of the
time zone surfaces only with a precision of 0,1 degree.

For this purpose, a gridfile is used, which contains a geometric grid of the
time zones. Before the first function call, the gridfile must be initialized
using the function settzgridfile(). You can download the GeoDLL supported
gridfile named GEODLLTZ.GRD directly from the KilletSoft website.
See http://www.killetsoft.de/p_gdlfzb_e.htm.

A distinction is made between national and international time zones. The
designation of a national time zone consists of an area name and a city name.
Example: "Europe/Berlin".
An international time zone consists dependent of the longitude a designation
between "UTC-12:00" and "UTC+12:00" and an international identifier between
"Alpha" and "Zulu". Example: "Offshore UTC+01:00/Alpha".
The parameter nTzType defines under which conditions the time zone is
determined:
 0: A national time zone will be determined, when the coordinate is onshore,
    otherwise an international time zone with a time zone index between 420
    and 444 will be determined.
10: A national time zone will be determined, when the coordinate is onshore,
    otherwise the time zone index 419 with the designation "Offshore/
    uninhabited" will be returned.
 2: A national time zone will be determined, when the coordinate is onshore or
    inside the twelve mile territorial limit, otherwise an international time
    zone with a time zone index between 420 and 444 will be determined.
12: A national time zone will be determined, when the coordinate is onshore or
    inside the twelve mile territorial limit, otherwise the time zone index 419
    with the designation "Offshore/uninhabited" will be returned.
 5: A international time zone with a time zone index between 420 and 444 will
    be determined.

With the determined GeoDLL time zone index diverse time zone calculations can
be performed by calling the following functions:
gettzcurrentbynum()  Determination of current time zone parameters
gettznamebynum()     Determination of a time zone designation
gettzparbynum()      Determination of common time zone parameters


The parameters are passed and/or returned as follows:
fLongitude   Geographic longitude of a coordinate in WGS84 datum, for which the
             corresponding time zone is to be calculated.

fLatitude    Geographic latitude of a coordinate in WGS84 datum, for which the
             corresponding time zone is to be calculated.

nTzType      The identifier specifies the conditions under which the time zone
             is to be determined. See description above.

nTimeZone    The calculated time zone index. The value is returned by reference.
(ref)

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.