Prototyp und Beschreibung der Funktion gettznumbycoordfast()

(Funktion der freischaltpflichtigen Gruppe "Zeitzonenberechnungen")

gettznumbycoordfast()
Schnelle Ermittlung eines GeoDLL-Zeitzonen-Index aus einer Koordinate.

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

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


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 und der Zwölfmeilenzone. Um die Dreimeilenzone, die 24-Meilen
Anschlusszone oder die 200-Meilen Wirtschaftszone einzubeziehen, muss die
Funktion gettznumbycoordexact() verwendet werden.

Die Funktion ermittelt aus einer geographischen Koordinate im Bezugssystem WGS84
(fLongitude, fLatitude) den GeoDLL-Zeitzonen-Index einer Zeitzone. Im Vergleich
mit der Funktion gettznumbycoordexact() ist gettznumbycoordfast() zwar erheblich
schneller, ermittelt aber die Zeitzonen in den Randgebieten der Zeitzonenflächen
nur mit einer Genauigkeit von 0,1 Grad.

Dazu wird eine Gitterdatei verwendet, in der ein geometrisches Gitter mit den
Zeitzonen enthalten ist. Die Gitterdatei muss vor dem ersten Funktionsaufruf mit
Hilfe der Funktion settzgridfile() initialisiert werden. Sie können die von
GeoDLL unterstützte Gitterdatei mit der Bezeichnung GEODLLTZ.GRD 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.
 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.
 5: Es wird nur die internationale Zeitzone mit einem Zeitzonen-Index zwischen
    420 und 444 ermittelt.

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.