Prototyp und Beschreibung der Funktion gettznumbycoordexact()

(Funktion der freischaltpflichtigen Gruppe "Zeitzonenberechnungen")

 

gettznumbycoordexact()
Genaue Ermittlung eines GeoDLL-Zeitzonen-Index aus einer Koordinate.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettznumbycoordexact(
     double fLongitude,
     double fLatitude,
     unsigned short nTzType,
     unsigned short *nTimeZone);

Prototyp der DLL-Funktion 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


Eine Zeitzone ist eine Region mit einer einheitlichen Standardzeit für
rechtliche, wirtschaftliche und soziale Zwecke. Zeitzonen sind primär vom
Längengrad abhängig, folgen aber sekundär den Grenzen von Staaten oder deren
administrativen Untereinheiten. Die von GeoDLL unterstützten Zeitzonen basieren
auf einer einheitlichen Namenskonvention von Paul Eggert, wie z.B.
Amerika/New_York und Europa/Paris. Die Zeitzonen entsprechen Offsets von der
Coordinated Universal Time (UTC) als eine Anzahl von Stunden (UTC-12 bis
UTC+12). Viele Staaten in höheren Breitengraden verwenden die Sommerzeit (DST)
in einen Teil des Jahres, die normalerweise durch das Vorstellen der Uhren um
eine Stunde realisiert wird.

Die Funktion berechnet die Zeitzonen wahlweise unter Einbeziehung der Küsten-
Basislinie, der Dreimeilenzone, der Zwölfmeilenzone, der 24-Meilen Anschlusszone
und der 200-Meilen Wirtschaftszone.

Die Funktion ermittelt aus einer geographischen Koordinate im Bezugssystem WGS84
(fLongitude, fLatitude) den GeoDLL-Zeitzonen-Index einer Zeitzone. Im Vergleich
mit der Funktion gettznumbycoordfast() ist gettznumbycoordexact() zwar
langsamer, ermittelt aber die Zeitzonen auch in den Randgebieten der
Zeitzonenflächen mit hoher Präzision.

Dazu wird eine Shapedatei verwendet, in der die Geometrien aller Zeitzonen
eingetragen sind. Die Shapedatei muss vor dem ersten Funktionsaufruf mit Hilfe
der Funktion settzshapefile() initialisiert werden. Sie können die von GeoDLL
unterstützte Shapedatei mit der Bezeichnung GEODLLTZ.SHP direkt von der
KilletSoft Internetseite herunterladen.
Siehe http://www.killetsoft.de/p_gdlfzb_d.htm.

Es wird zwischen nationalen und internationalen Zeitzonen unterschieden. Die
Bezeichnung einer nationalen Zeitzone besteht aus einem Gebietsnamen und einem
Stadtnamen. Beispiel: "Europa/Berlin".
Eine internationale Zeitzone besteht aus einer vom Längengrad abhängigen
Bezeichnung zwischen "UTC-12:00" und "UTC+12:00" und einer internationalen
Kennung zwischen "Alpha" und "Zulu". Beispiel: "Ozean UTC+01.00/Alpha".
Im Parameter nTzType wird festgelegt, unter welchen Bedingungen die Zeitzone
ermittelt wird:
 0: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland liegt, andernfalls wird eine internationale Zeitzone mit einem
    Zeitzonen-Index zwischen 420 und 444 ermittelt.
10: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland liegt, andernfalls wird der Zeitzonen-Index 419 mit der
    Bezeichnung "Offshore/unbewohnt" zurück gegeben.
 1: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der Dreimeilenzone liegt, andernfalls wird eine
    internationale Zeitzone mit einem Zeitzonen-Index zwischen 420 und 444
    ermittelt.
11: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der Dreimeilenzone liegt, andernfalls wird der
    Zeitzonen-Index 419 mit der Bezeichnung "Offshore/unbewohnt" zurück
    gegeben.
 2: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der Zwölfmeilenzone liegt, andernfalls wird eine
    internationale Zeitzone mit einem Zeitzonen-Index zwischen 420 und 444
    ermittelt.
12: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der Zwölfmeilenzone liegt, andernfalls wird der
    Zeitzonen-Index 419 mit der Bezeichnung "Offshore/unbewohnt" zurück
    gegeben.
 3: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der 24-Meilenzone liegt, andernfalls wird eine
    internationale Zeitzone mit einem Zeitzonen-Index zwischen 420 und 444
    ermittelt.
13: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der 24-Meilenzone liegt, andernfalls wird der
    Zeitzonen-Index 419 mit der Bezeichnung "Offshore/unbewohnt" zurück
    gegeben.
 4: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der 200-Meilenzone liegt, andernfalls wird eine
    internationale Zeitzone mit einem Zeitzonen-Index zwischen 420 und 444
    ermittelt.
14: Es wird eine nationale Zeitzone ermittelt, wenn die Koordinate auf dem
    Festland oder innerhalb der 200-Meilenzone liegt, andernfalls wird der
    Zeitzonen-Index 419 mit der Bezeichnung "Offshore/unbewohnt" zurück
    gegeben.
 5: Es wird nur die internationale Zeitzone mit einem Zeitzonen-Index zwischen
    420 und 444 ermittelt. Diese Option sollte besser mit der schnelleren
    Funktion gettznumbycoordfast() verwendet werden.

Mit dem ermittelten GeoDLL-Zeitzonen-Index können Zeitzonen-Berechnungen durch
Aufruf einer der folgenden Funktionen durchgeführt werden:
gettzcurrentbynum()  Ermittlung der aktuellen Zeitzonen-Parameter
gettznamebynum()     Ermittlung der Zeitzonenbezeichnung
gettzparbynum()      Ermittlung allgemeiner Zeitzonen-Parameter


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
fLongitude   Geographische Länge einer Koordinate im Bezugssystem WGS84, für
             welche die passende Zeitzone berechnet werden soll.

fLatitude    Geographische Breite einer Koordinate im Bezugssystem WGS84, für
             welche die passende Zeitzone berechnet werden soll.

nTzType      Die Kennung legt fest, unter welchen Bedingungen die Zeitzone
             ermittelt werden soll. Beschreibung siehe oben.

nTimeZone    Der ermittelte Zeitzonen-Index. Der Wert wird per Referenz zurück-
(ref)        gegeben.

returnWert   Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE.


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"Zeitzonenberechnungen". Sie wird zusammen mit den anderen Funktionen der
Gruppe durch die Eingabe der bei der Vertriebsfirma erworbenen Freischalt-
parameter per Aufruf der Funktion setunlockcode() zur uneingeschränkten Nutzung
frei geschaltet. Ohne die Freischaltung sind nur wenige Funktionsaufrufe zu
Testzwecken (Sharewareprinzip) möglich.