Prototyp und Beschreibung der Funktion gettzparbynum()

(Funktion der freischaltpflichtigen Gruppe "Zeitzonenberechnungen")

 

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

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
__declspec(dllimport) unsigned long __stdcall gettzparbynum(
     unsigned short nTimezone,
     float *fUtc,
     float *fDst,
     char **pszDstStart,
     char **pszDstEnd);

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function gettzparbynum(;
     nTimezone as word,;                // 2 Byte
     fUtc ref real4,;                   // 4 Byte
     fDst ref real4,;                   // 4 Byte
     pszDstStart ref psz,;              // 4 Byte, char**, 10 alloc.
     pszDstEnd ref psz);                // 4 Byte, char**, 10 alloc.
as logic pascal:geodll32.gettzparbynum  // 4 Byte

Die Allokation von Speicher für "ref psz" / "char**" ist nur notwendig,
wenn zuvor setstringallocate(FALSE) aufgerufen worden ist.


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 Zeitzonen-Parameter
UTC, DST und Schlüssel für den Beginn und das Ende der Sommerzeit-Periode (DST-
Periode).

Die bis zu sechsstelligen Schlüssel für den Beginn und das Ende der DST-Periode
sind wie folgt aufgebaut:
  Zeichen 1 und 2:  Schlüssel für den Monat (01 bis 12)
  Zeichen 3 bis 6:  Schlüssel für den Tag
     2 Ziffern:
       Die beiden Ziffern stellen einen festen Tag im Monat dar (01 bis 31)
     2 Buchstaben und 2 Ziffern:
       Die beiden Buchstaben stellen den Wochentag im Monat dar:
         SU Sonntag   MO Montag   TU Dienstag   WE Mittwoch   TH Donnerstag
         FR Freitag   SA Samstag
       Die beiden Ziffern stellen den frühstmöglichen Tag im Monat (›=) dar,
       auf das der Wochentag fallen kann.
     2 Buchstaben und ein "L":
       Die beiden Buchstaben stellen den Wochentag im Monat wie oben dar.
       Der Buchstabe "L" bedeutet das der letzte Wochentag im Monat gemeint ist.
     Beispiele:
       0321    der 21. März
       03SU08  der Sonntag am/nach dem 8. März
       03FR23  der Freitag am/nach dem 23. März
       03SUL   der letzte Sonntag im März
       04THL   der letzte Donnerstag im April

Wenn der Schlüssel pszDstStart für den Beginn der DST-Periode ein höheres Datum
enthält als der Schlüssel pszDstEnd 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, sind die beiden Schlüssel
pszDstStart und PszDstEnd leer (NullStrings) und der Parameter fDst enthält den
Wert 0.

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.

pszDstStart  Schlüssel für das Datum, an dem die DST-Periode beginnt. Der String
(ref)        wird per Referenz zurückgegeben. Syntax siehe oben.
             Achtung: "ref pszDstStart" entspricht "char**" in C. Es müssen 10
             Byte Speicher für den Null terminated string in Abhängigkeit vom
             Aufruf der Funktion setstringallocate() allokiert werden. Beachten
             Sie dazu die Hinweise in der Beschreibung der Funktion
             setstringallocate()".

pszDstEnd    Schlüssel für das Datum, an dem die DST-Periode endet. Der String
(ref)        wird per Referenz zurückgegeben. Syntax siehe oben.
             Achtung: "ref pszDstEnd" entspricht "char**" in C. Es müssen 10
             Byte Speicher für den Null terminated string in Abhängigkeit vom
             Aufruf der Funktion setstringallocate() allokiert werden. Beachten
             Sie dazu die Hinweise in der Beschreibung der Funktion
             setstringallocate()".

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.