|
Prototype and description of the function gettznumbycoordexact() (Function of the unlock requiring group "Time Zone Calculations") |
|
gettznumbycoordexact()
Exact 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 gettznumbycoordexact(
double fLongitude,
double fLatitude,
unsigned short nTzType,
unsigned short *nTimeZone);
Prototype of the DLL function in Visual Objects syntax:
_DLL function gettznumbycoordexact(;
fLongitude as real8,; // 8 Byte
fLatitude as real8,; // 8 Byte
nTzType as word,; // 2 Byte
nTimeZone ref word); // 4 Byte
as logic pascal:geodll32.gettznumbycoordexact // 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, the Three Mile Territorial Limit, the Twelve Mile Territorial Limit,
the 24-Mile Contiguous Zone and the 200-Mile Exclusive Economic Zone.
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 gettznumbycoordfast(), the function gettznumbycoordexact() is
slower, but it determines the time zone in the border areas of the time zone
surfaces with high precision.
For this purpose, a shapefile is used, which contains the geometries of the
time zones. Before the first function call, the shapefile must be initialized
using the function settzshapefile(). You can download the GeoDLL supported
shapefile named GEODLLTZ.SHP 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.
1: A national time zone will be determined, when the coordinate is onshore or
inside the three mile territorial limit, otherwise an international time
zone with a time zone index between 420 and 444 will be determined.
11: A national time zone will be determined, when the coordinate is onshore or
inside the three mile territorial limit, 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.
3: A national time zone will be determined, when the coordinate is onshore or
inside the 24 mile territorial limit, otherwise an international time zone
with a time zone index between 420 and 444 will be determined.
13: A national time zone will be determined, when the coordinate is onshore or
inside the 24 mile territorial limit, otherwise the time zone index 419
with the designation "Offshore/uninhabited" will be returned.
4: A national time zone will be determined, when the coordinate is onshore or
inside the 200 mile territorial limit, otherwise an international time zone
with a time zone index between 420 and 444 will be determined.
14: A national time zone will be determined, when the coordinate is onshore or
inside the 200 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. This option should better be used with the faster function
gettznumbycoordfast().
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.
|