Prototyp und Beschreibung der Funktion gettzcurrentbynum()

(Funktion der freischaltpflichtigen Gruppe "Zeitzonenberechnungen")

 

gettzcurrentbynum()
Ermittlung der aktuellen Zeitzonen-Parameter aus einem GeoDLL-Zeitzonen-Index.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
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);

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


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 ermittelt aus einem GeoDLL-Zeitzonen-Index die aktuellen Zeitzonen-
Parameter UTC, DST und Lokalzeit sowie die Daten für den Beginn und das Ende der
Sommerzeit-Periode (DST-Periode). Flags zeigen an, ob in der Zeitzone eine
DST-Periode verwendet wird und ob sich die DST-Periode, wie in der südlichen
Hemisphäre üblich, über den Jahreswechsel erstreckt. Für die Berechnungen
verwendet die Funktion das aktuelle Datum aus dem Computer.

Die Lokalzeit fLocalTime setzt sich aus der UTC und der DST zusammen, wobei die
DST nur addiert wird, wenn das aktuelle Datum innerhalb der DST-Periode liegt.

Der Beginn und das Ende der DST-Periode wird in den Parametern dwDstStart und
dwDstEnd als Datum des aktuellen Jahres mit folgender Syntax zurück gegeben:
jjjjmmtt
  jjjj vierstellige Angabe des aktuellen Jahres
  mm   zweistellige Angabe des Monats, in dem die DST-Periode wechselt
  tt   zweistellige Angabe des Tages, an dem die DST-Periode wechselt

Wenn dwDstStart für den Beginn der DST-Periode ein höheres Datum enthält als
dwDstEnd für das Ende der DST-Periode, befindet sich die Zeitzone auf der
südlichen Hemisphäre. Die DST-Periode erstreckt sich dabei über den
Jahreswechsel.

Wenn in der Zeitzone keine DST-Periode verwendet wird, enthalten die Parameter
dwDstStart, dwDstEnd und fDst den Wert 0 und die Parameter lIsDstActiv und
lIsSouthHemi sind FALSE.

Der benötigte GeoDLL-Zeitzonen-Index kann wir folgt ermittelt werden:
gettznumbycoordexact()  Genaue Ermittlung des Index aus einer Koordinate
gettznumbycoordfast()   Schnelle Ermittlung des Index aus einer Koordinate
Liste                   Aus der Liste der von GeoDLL unterstützten Zeitzonen


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
nTimeZone    Zeitzonen-Index, der zuvor mit anderen Zeitzonen-Funktionen
             berechnet worden ist oder der Liste entnommen worden ist.

fUtc         Offset der Zeitzone von der Coordinated Universal Time (UTC) in
(ref)        Stunden. Der Wert wird per Referenz zurückgegeben.

fDst         DST (Daylight Saving Time) in Stunden, wenn in der Zeitzone die
(ref)        Sommerzeit verwendet wird. Der Wert wird per Referenz zurück-
             gegeben.
0.0:         Wenn in der Zeitzone kein DST verwendet wird.

lIsDstActiv  Flag für die Aktivität der DST am aktuellen Datum. Das Flag wird
(ref)        per Referenz zurückgegeben.
TRUE:        Heutiges Datum liegt innerhalb der DST-Periode.
FALSE:       Heutiges Datum liegt außerhalb der DST-Periode oder in der Zeitzone
             wird kein DST verwendet.

dwDstStart   Datum, an dem die DST-Periode beginnt. Der Wert wird per Referenz
(ref)        zurückgegeben. Syntax siehe oben.

dwDstEnd     Datum, an dem die DST-Periode endet. Der Wert wird per Referenz
(ref)        zurückgegeben. Syntax siehe oben.

lIsSouthHemi Flag für die Lage der Zeitzone auf der südlichen Hemisphäre. Das
(ref)        Flag wird per Referenz zurückgegeben.
TRUE:        dwDstStart › dwDstEnd --› südliche Hemisphäre
FALSE:       dwDstStart ‹ dwDstEnd --› nördliche Hemisphäre

fLocalTime   Lokalzeit in der der Zeitzone am aktuellen Datum unter
(ref)        Berücksichtigung der DST-Periode als Offset von der Coordinated
             Universal Time (UTC) in Stunden. Der Wert wird per Referenz
             zurückgegeben.
             fLocalTime = fUtc + fDst

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.